@mrciphersmith/keryx 0.3.44 → 0.3.46

package/src/gdskills/bundled/skills/core/reviewer-skill-creator/SKILL.md

@@ -53,28 +53,28 @@ these go.
 
 ## Bulk import of overlay reviewers
 
-When the overlays already exist as `review-vantage-*` skill packages (for
-example an overlay skill tree with `review-vantage-*` packages), do not recreate them one by one.
+When the reviewers already exist as skill packages in a tree someone else maintains, import
+them instead of recreating them one by one. Dry-run first, then the same command without it:
 
 ```bash
-keryx skills import --from <overlay-home> --module review
-# alias: keryx review import --from <overlay-home>
+keryx review import --from <overlay-home> --only 'review-acme-*' --dry-run
+keryx review import --from <overlay-home> --only 'review-acme-*'
+keryx review reviewers              # every imported name must be listed here
+keryx skills remove review/<name>   # undo one
 ```
 
-That copies every `review-vantage-*` package into
-`.metaproject/project-skills/review/`, stamps Origin on each SKILL.md, and is
-the same discovery `review-orchestrator` uses. Generic copies of keryx
-reviewers (`review-logic`, `review-frontend`, …) are skipped on purpose —
-those would shadow the bundled engine.
+`keryx review import` is the review-shaped spelling of `keryx skills import --module review`:
+same importer, module implied. A tree of several packages is refused, with the candidate list,
+until `--only <glob>` names the ones you want: `review-orchestrator` dispatches every package in
+module `review`, and one with no path gate is dispatched on every round. Import reviewers only —
+an orchestrator or facade, a deprecated alias, a report generator, or anything with no review
+contract does not belong there. One package directory passed as `--from` needs no `--only`.
 
-One overlay package:
-
-```bash
-keryx review import --from <overlay-home>/skills/review-vantage-frontend
-```
-
-Then `keryx review reviewers`. Until that list shows the names, they are not
-wired.
+Read `SKILL.detail.md` beside this file before running an import. It is the worked example, with
+real output: the refusals, what each run writes, how `flags`, `paths`, `pathsSource`,
+`stackRequires`, `unresolvedRules` and `drift` are derived, rule collisions, undo with
+`keryx skills remove`, refresh, the per-clone note, and the `review-learning.config.json` shape.
+Until `keryx review reviewers` shows the names, they are not wired.
 
 ---
 
@@ -221,8 +221,8 @@ source file differs from what was imported. It does **not** mean the reviewer is
 
 Re-read the source, diff it against what the skill encodes, and then decide per
 change: fold it in, or record in the skill why this project deliberately differs.
-Re-run Step 2's command with the same `--name` to re-record the hash once the
-skill matches the source again.
+For a reviewer written here, re-run Step 2's command with the same `--name` to re-record the hash once it matches the source again.
+For an imported package, `keryx skills update review/<name>` re-reads its Origin and overwrites the SKILL.md — see `SKILL.detail.md`.
 
 A deliberate divergence that is written down is a decision. The same divergence
 undocumented is drift that will be silently "fixed" by whoever refreshes next.
@@ -239,7 +239,7 @@ undocumented is drift that will be silently "fixed" by whoever refreshes next.
 | Change a reviewer keryx ships | NO | edit `src/gdskills/bundled/skills/review/` and open a PR |
 | Update a skill from review findings | NO | `entity-skill-learner`, `keryx skills learn` |
 | Decide which reviewers a round dispatches | NO | `review-orchestrator` |
-| Import a tree of overlay reviewers | YES — `keryx skills import --from <dir> --module review` (`keryx review import` alias) | — |
+| Import a tree of overlay reviewers | YES — `keryx review import --from <dir> --only '<glob>'`, dry-run first (`SKILL.detail.md`) | — |
 | Import a non-review SKILL.md / GitHub URL | NO | `entity-skill-creator` / `keryx skills import` |
 
 ---

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

@@ -32,7 +32,7 @@ keryx rules distill
    - `.metaproject/rules/entrypoints/index.md`
    - `.metaproject/rules/entrypoints/*.md`
    - `.metaproject/project-skills/entrypoints/*/SKILL.md`
-   - compact `AGENTS.md` and `CLAUDE.md` still point to `.metaproject/index.md`
+   - the `.metaproject/index.md` block sits where `agentEntrypoints.root` says: `CLAUDE.local.md` and a regenerated `AGENTS.override.md` under scope `local` (the team files are rewritten without it), the team file itself under scope `shared`
 4. If the command changed root entrypoints, check that only global/personal or
    highest-priority always-on instructions remain there.
 5. Run focused verification:
@@ -51,7 +51,7 @@ Stop and re-read this skill if you are thinking:
 | Rationalization | Rebuttal |
 |---|---|
 | "`keryx rules distill` exited 0, so the split is correct." | Exit 0 says the command ran, not that it split well. It happily writes an empty rule, a rule titled after a heading it could not classify, and two rules holding the same paragraph. Open every file listed in step 3 before reporting anything. |
-| "The root entrypoint is short now, so the job is done." | Shortness is a side effect, not the goal. A root that no longer points at `.metaproject/index.md`, or that lost an always-on instruction into a rule nothing loads, is a regression that looks like success on a line count. |
+| "The root entrypoint is short now, so the job is done." | Shortness is a side effect, not the goal. An entrypoint set from which no file points at `.metaproject/index.md` any more, or a root that lost an always-on instruction into a rule nothing loads, is a regression that looks like success on a line count. |
 | "This section read like a project rule, so I moved it out of the root." | Global, personal and highest-priority always-on instructions stay in the root by design. If you had to guess which kind a section was, it belongs in the ambiguous list for a human — not silently in a rule file. |
 | "The project has no flow, so I can skip verification." | `keryx flow check` is not conditional either — with no flows it reports `All flows are consistent.` and exits 0. `keryx rules sync` runs every time; skipping it ships a rules tree whose index and files disagree. |
 | "`keryx rules distill` rewrote the root files, so I don't need to read them." | The rewrite is exactly what needs checking. Reading the post-distill `AGENTS.md` and `CLAUDE.md` is the only way to see what was carried out of them. |
@@ -63,7 +63,7 @@ Before reporting, all of these must hold:
 - `keryx rules sync` exits 0.
 - `.metaproject/rules/entrypoints/index.md` exists and names every file written under `.metaproject/rules/entrypoints/`.
 - Every generated rule and project-skill file is non-empty and was read, not just listed.
-- `AGENTS.md` and `CLAUDE.md` both still reference `.metaproject/index.md`.
+- Claude and Codex still reach `.metaproject/index.md`: the managed block is in `CLAUDE.local.md` and `AGENTS.override.md` (scope `local`; Codex `skip` writes none) or in the shared `CLAUDE.md` / `AGENTS.md` — never in both.
 - `keryx flow check` exits 0. It takes no id and checks every flow package in the project, so a distill that corrupted one reports here even though the distill never touched flows.
 - Every section you could not confidently classify appears in the ambiguous list of the Output Contract. An empty ambiguous list on a large entrypoint is a claim, and it must be a true one.
 

package/src/gdskills/bundled/skills/platform/claude-md-management/SKILL.md

@@ -85,7 +85,7 @@ Present diff preview:
 - NEVER remove existing entries without explanation
 - NEVER add entries that duplicate what's already there
 - Keep CLAUDE.md files under 100 lines
-- Prefer project-level for project-specific things
+- Prefer project-level for project-specific things; never write inside the `<!-- keryx:index -->` markers (in `CLAUDE.local.md` by default, `CLAUDE.md` under shared scope) — keryx regenerates that block
 
 ## Red Flags
 

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

@@ -181,13 +181,13 @@ Flags:
 #### A3. useEffect Misuse
 
 - [ ] `useEffect` must not contain business logic
-- [ ] `useEffect` must not call `store.init()`, `store.load()`, or `store.onMount()` — lifecycle initialization is the parent store's responsibility
+- [ ] `useEffect` must not fetch data or run business logic through the store: no `store.load()` / `store.loadX()`, and no `init()` of a child store that the parent store owns. The lifecycle bridge `useEffect(() => { store.onMount(); return () => store.onUnmount(); }, [store])` is correct and is not flagged (D6) — it hands the mount event to the store, which decides what to load
 - [ ] `useEffect` must not contain API calls or IO
 - [ ] `useEffect` used to synchronize component state with store state is a sign the component should be an `observer` instead
 - [ ] Every `useEffect` that creates a subscription, timer, or listener MUST return a cleanup function
 
 Flags:
-- `useEffect` calls `store.init()` or `store.loadX()` — **major**
+- `useEffect` calls `store.loadX()`, or a child store's `init()` that the parent store owns — **major** (`store.onMount()` / `store.onUnmount()` in the bridge form is not this)
 - `useEffect` contains `fetch()` or IO — **major** (API in component)
 - `useEffect` contains business logic / state derivation — **major**
 - `useEffect` creates a subscription/timer/listener with no cleanup return — **major** (memory leak)
@@ -350,13 +350,13 @@ Flags:
 
 #### B10. Lifecycle Initialization and Disposal
 
-- [ ] `init()` / `onMount()` of a child store is called from the **parent store's** `init()` / `onMount()`, NOT from a component `useEffect`
+- [ ] `init()` / `onMount()` of a **child** store is called from the **parent store's** `init()` / `onMount()`, not from a component `useEffect`. The component's own store is different: its `onMount()` / `onUnmount()` are called from the component through the lifecycle bridge (D6), and that is correct
 - [ ] Components must NOT trigger store data loading via `useEffect` (e.g., `useEffect(() => { store.load() }, [])`)
 - [ ] Parent store's `onUnmount()` / `dispose()` MUST call `childStore.dispose()` to prevent stale-state updates
 - [ ] Store `dispose()` MUST set `this.disposed = true` before canceling async work
 
 Flags:
-- Component `useEffect` calls `store.loadX()`, `store.init()`, or `store.onMount()` — **major**
+- Component `useEffect` calls `store.loadX()`, or a child store's `init()` / `onMount()` that the parent store owns — **major**. Do not flag the bridge `useEffect(() => { store.onMount(); return () => store.onUnmount(); }, [store])`
 - Parent store does not call `child.dispose()` in `onUnmount()` / `dispose()` — **major**
 - Missing `disposed` flag in store with async operations — **major**
 
@@ -468,7 +468,7 @@ const store = useLocalObservable(() => props.store ?? new ComponentStore(props.s
 
 #### D6. Store Lifecycle Bridge via useEffect
 
-When a project routes store lifecycle through `useEffect` as a documented pattern:
+The component tells its store that it mounted and unmounted; the store decides what that means:
 
 ```typescript
 useEffect(() => {
@@ -477,11 +477,11 @@ useEffect(() => {
 }, [store]);
 ```
 
-This IS the correct lifecycle bridge in projects that use this pattern — do NOT flag as an A3 violation. The A3 rule ("useEffect must not call store.init()") targets implicit data-loading, not explicit lifecycle hooks.
+This is the correct lifecycle bridge — do not flag it under A3 or B10. Those rules target a data fetch or business logic placed in the effect, and a component reaching into a child store the parent store owns; they do not target the lifecycle hooks themselves. What `onMount()` does (load, subscribe, initialise child stores) is store code and is reviewed as store code.
 
 Distinction:
 - `useEffect(() => { store.onMount(); return () => store.onUnmount(); }, [store])` — correct lifecycle bridge — **do not flag**
-- `useEffect(() => { store.loadData(); }, [])` — data trigger in component — **major** (A3 violation regardless of project conventions)
+- `useEffect(() => { store.loadData(); }, [])` or `useEffect(() => { store.childStore.init(); }, [])` — data trigger, or a child store's lifecycle the parent store owns, run from the component — **major** (A3 / B10, regardless of project conventions)
 
 #### D7. JSX and Naming Conventions
 

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

@@ -14,16 +14,99 @@ them from the reviewer's prose.
 
 | Field | Use |
 |---|---|
-| `flags` | A flag the user passed that is in this list selects the reviewer **explicitly** — it is then never path-gated, like any flag-selected reviewer. `--all` selects every project reviewer. |
+| `flags` | The reviewer's selection flags: `metadata.flags` from its frontmatter when it has at least one non-empty entry — then it takes precedence, even when none of its entries turns out to be a flag or it holds only `--all`, and the reviewer has no flags — otherwise the flags its description names. An empty `metadata.flags` (`[]`, `''`) leaves the description's flags in force. Already normalised (lower-case, `--` prefixed), so compare a passed flag with them as they are. A flag the user passed that is in this list selects the reviewer. Whether that selection is also exempt from the path gate depends on `familyFlags`. `--all` selects every project reviewer. |
+| `flagWarnings` | One line per `metadata.flags` entry that was dropped because it is not a flag after normalising, plus one more when that left the reviewer with no flags. A list of only `--all` leaves no flags and no warning. Empty in the ordinary case. A dropped entry selects nothing: do not match a passed flag against the raw spelling in the reviewer's frontmatter. Dispatch the reviewer as its other fields say, and name the warnings once in the report — a reviewer its author meant to be flag-selectable is not. Never a finding against the code. |
+| `familyFlags` | The subset of `flags` that at least one other project reviewer also carries. A passed flag listed here is a **family flag**: it selects this reviewer, and the reviewer stays path-gated. A passed flag that is in `flags` and not here is unique to this reviewer: the selection is **explicit** and never path-gated, like any flag-selected bundled reviewer. |
 | `paths` | Its path triggers for the **path gate**. No file in scope A matches → `Skipped reviewers`, reason `no-matching-paths`. |
-| `pathsSource` | `metadata` (declared `metadata.paths`) or `description` (globs read out of its description). `none` means there is nothing to gate on: **dispatch it** — ambiguity includes. |
+| `pathsSource` | `metadata` (declared `metadata.paths`) or `description` (globs read out of its description, and the literal file paths such as `src/utils/column-zone.ts` listed beside them; a cited `.md` / `.mdc` document and a `.metaproject/` path are not triggers). A description with no glob gives `none` even when it names a file: a literal path counts only beside a glob. `none` means there is nothing to gate on: **dispatch it** — ambiguity includes. |
 | `stackRequires` | Apply stack scoping exactly as for a bundled reviewer carrying `metadata.stack_requires`. |
-| `unresolvedRules` | Rules it cites that the project does not have. Dispatch it anyway, tell it in the prompt which rules are absent, and name them once in the report with the fix (`keryx review import --from <overlay>` copies them). Never a finding against the code. |
+| `unresolvedRules` | Rules it cites that the project does not have. Dispatch it anyway, tell it in the prompt which rules are absent, and name them once in the report with the fix (`keryx review import --from <overlay> --only '<glob>'` copies them). Never a finding against the code. |
+| `shadowedRules` | `[{ ref, resolved }]`: rules it cites by one path and must read from another. The project holds its own version of the rule at `resolved` — the reference's slot under `.metaproject/rules/project/`, the whole reference kept (`core/x.mdc` → `.metaproject/rules/project/core/x.mdc`) — which answers the reference before the file `ref` names. In the dispatch prompt, tell the reviewer to read `resolved` in place of `ref` — see "Dispatching a project reviewer" below. Not a defect and not reported as one. |
+| `unresolvedReferences` | `[{ ref, reason }]`: other references in its text that will not hold. `missing` — a backticked `skills/…` or `rules/…` path ending `.md` / `.json` with no file under `.metaproject/`; `non-portable` — a rule cited by an absolute or `~` path, true on one machine at most. Dispatch it anyway, tell it in the prompt which references are absent, and name them once in the report. Never a finding against the code. |
+
+`metadata.paths`, `metadata.flags` and `metadata.stack_requires` are read by
+one frontmatter reader that supports a YAML subset (BOM and CRLF accepted,
+trailing `# comments` dropped, `paths` and `flags` as a flow, block or
+comma-separated list, `stack_requires` as a string, only keys directly under
+`metadata:`); a shape outside it reads as not declared.
+`reviewer-skill-creator`'s `SKILL.detail.md` lists the subset. The inventory
+has already applied it — use the fields, not the raw frontmatter.
 
 A description saying another entry point dispatches it ("Dispatched by
 vantage-review …") is its author's routing note, not a restriction: this
 orchestrator dispatches it through the fields above.
 
+### Family flags — why a shared flag does not lift the path gate
+
+An overlay usually gives every reviewer it ships the same umbrella flag beside
+the reviewer's own: eight reviewers all carrying `--acme`, each also carrying
+`--acme-styling`, `--acme-testing` and so on. Read as explicit, `--acme` would
+dispatch all eight against a diff that touches one of their path sets — the
+waste the path gate exists to stop, brought back by a flag.
+
+So the two cases are told apart by how many project reviewers carry the flag,
+and the inventory reports the answer per reviewer in `familyFlags` rather than
+leaving the orchestrator to count:
+
+| Passed flag | In this reviewer's `familyFlags`? | Result |
+|---|---|---|
+| `--acme` | yes (shared) | selected, then path-gated on its `paths` |
+| `--acme-styling` | no (unique to it) | selected explicitly, not path-gated |
+| both | — | the unique flag wins: not path-gated |
+
+A family member gated out goes to `Skipped reviewers` with reason
+`no-matching-paths` like any other gated reviewer. `pathsSource: none` still
+means dispatch. An inventory that has no `familyFlags` field comes from a keryx
+that predates it: treat every passed flag as explicit, which is the earlier
+behaviour, and say so once in the report.
+
+### Dispatching a project reviewer — by its package, not by its name
+
+Each `project` entry carries `path`, the directory its package is registered
+at. Dispatch it with the absolute path of `<path>/SKILL.md` as `skill_path` in
+the reviewer input, and state in the prompt that this file is the reviewer's
+definition and overrides the built-in definition of any agent type with the
+same name. `skill_path` in the reviewer input is set for project reviewers
+only, and it carries that override. A bundled reviewer's input never has it:
+when one runs through the `general-purpose` fallback, the prompt text names its
+skill file and `review_context.review_plan.dispatch_plan` records the path, but nothing is
+being overridden, so the input field stays out. This holds on every branch of "Agent Runtime Compatibility" in
+SKILL.md: when a same-named agent type exists, dispatch it **with** the path
+and the override sentence; when none exists, dispatch `general-purpose` with
+the same two things.
+
+The reason is a name collision nobody chose. A runtime can ship an agent type
+whose name equals a project reviewer's — an earlier copy of the same reviewer,
+or an unrelated one. Dispatched by name alone, the round runs that built-in
+prompt and files its findings under the project reviewer's name, and nothing in
+the report shows the project's own text was never read.
+
+If `<path>/SKILL.md` does not exist, the reviewer is `BLOCKED`: record the
+missing path, continue with the independent reviewers, and do not run the
+same-named agent type or any other reviewer in its place. A substituted
+reviewer reads as coverage the round did not have.
+
+**Shadowed rules go into the same prompt.** For every entry in the reviewer's
+`shadowedRules`, add one line to the dispatch: "where your text names `<ref>`,
+read `<absolute path of resolved>` instead" — for a reviewer citing
+`core/error-handling.mdc`, that is
+`<project root>/.metaproject/rules/project/core/error-handling.mdc`. Take the
+path from `resolved`; do not build it from the rule's filename, because the slot
+keeps the reference's directory and a file lying directly in `rules/project/`
+answers only a literal `project/<name>.mdc` citation. An import keeps an
+overlay's rule in that slot whenever a file already answers the reference with
+other content, or the name is one keryx also ships under `rules/core`, because
+`keryx init`, `keryx update` and the legacy-profile `keryx skills install`
+overwrite `rules/core` with keryx's own rules (the manifest form with
+`--target keryx-shell` skips an existing file it did not record unless
+`--force`; see "Skills present only when installed"). The reviewer's text was written against the overlay and
+still says `core/<name>.mdc`, so followed literally it reads keryx's generic
+rule of the same name and reviews against the wrong standard — silently, since
+both files exist. The inventory computes the project-first order and reports
+it; no loader applies it. This line in the dispatch is the only place it takes
+effect, and a project reviewer run outside this orchestrator reads what its
+text names.
+
 ### `drift` — the source moved, the reviewer did not
 
 A project reviewer built from an external file — a rules file, a review profile,
@@ -32,7 +115,7 @@ import. `keryx review reviewers` re-reads the source and reports:
 
 | `drift` | Meaning | What to do this round |
 |---|---|---|
-| `none` | No external source; written here | Nothing |
+| `none` | No origin recorded; written here. The text row reads `(no recorded origin)` | Nothing |
 | `clean` | Source matches the import | Nothing |
 | `changed` | Source has moved on since import | Dispatch it, and say so in the report |
 | `missing` | Source can no longer be read | Dispatch it, and say so in the report |
@@ -44,6 +127,127 @@ suppressing it would trade real coverage for tidiness. Record the drift in
 profile is due a re-read. Never file it as a finding against the code under
 review: it is a fact about the review, not about the diff.
 
+## Skills present only when installed
+
+SKILL.md names five skills that the `minimal` and `recommended` profiles do not
+install — they are in the `full` profile only (`src/gdskills/catalog.ts`):
+
+| Skill | Reached through |
+|---|---|
+| `review-pr-feedback` | "A round never answers a pull request another skill is answering" |
+| `code-ai-review` | `--code-ai`, `--legacy-profiles` |
+| `code-learned-review` | `--learned`, `--legacy-profiles` |
+| `code-style-review` | `--code-style`, `--legacy-profiles` |
+| `code-mobx-store-review` | `--mobx-store`, `--legacy-profiles` |
+
+Whether one is **present** is read from `keryx review reviewers --json`, and
+the answer depends on the inventory's `bundledSource`, which says which tree
+the `bundled` half was read from. Do not infer presence from the flag table,
+which describes what keryx ships, not what this project has.
+
+| `bundledSource` | What the `bundled` half is | Is a listed skill installed here? |
+|---|---|---|
+| `"project"` | this project's `.metaproject/skills/gdskills/review` | yes; one that is not listed is not installed |
+| `"package"` | the review skills the keryx package itself ships | the list cannot say |
+| `"not-found"` | empty — neither tree could be located (the command exits 1) | the list cannot say |
+
+`"package"` means the project has no `.metaproject/skills/gdskills/review`
+directory at all — a worktree or clone whose `.metaproject/` holds only data,
+for instance. The inventory then lists every review skill in the package, all
+five above included, whatever profile the project would install, and each
+entry's `path` is relative to the keryx package (`src/gdskills/bundled/…`), not
+to the project. Nothing is installed in this project in that state, so a name
+being in the list is not evidence that it is, and a name missing from it is not
+what `not-installed` means either. Decide each of the five by what can actually
+be dispatched: if the runtime has an agent type of that exact name ("Agent
+Runtime Compatibility" in SKILL.md), the skill is usable and is dispatched as
+any other reviewer; if it does not, record `not-installed` with the command
+below, because the project holds no skill file to hand a `general-purpose`
+agent. Say once in the report that the bundled half came from the package, so
+nobody reads the round's reviewer list as this project's install.
+
+`"not-found"` is a failed inventory, not an empty install: report it and do not
+record any reviewer as `not-installed` on its strength.
+
+When one is absent:
+
+- **A legacy reviewer a flag asked for** is not dispatched and not replaced.
+  Record it in `Skipped reviewers` with reason `not-installed` and the command
+  below. `--legacy-profiles` and `--all` dispatch the legacy reviewers that are
+  installed and record the others the same way. Leave an absent reviewer out of
+  the `Optional legacy/profile reviewers` preview: offering a flag that cannot
+  run is worse than not offering it.
+- **`review-pr-feedback`** changes nothing about a round. No caller can declare
+  that it owns a pull request's reply, so this orchestrator owns the reply as it
+  does by default. If the user wants existing pull-request comments interpreted
+  and answered, say the skill is not installed and give the command; do not
+  improvise its workflow from this file.
+
+Adding one. The commands are `keryx skills install` in its two forms
+(`src/commands/skills.ts`):
+
+```bash
+# everything the full profile holds, including all five
+keryx skills install --profile full
+
+# manifest installer: the generic review module only — review-pr-feedback,
+# code-ai-review, code-learned-review and code-style-review among its skills
+keryx skills install --profile core --target keryx-shell
+
+# manifest installer: add the MobX component to a profile — code-mobx-store-review
+keryx skills install --profile <manifest-profile> --with capability:mobx --target keryx-shell
+```
+
+What those flags do and do not reach:
+
+- `--target keryx-shell` is what writes under `.metaproject/skills/gdskills/`,
+  where the inventory looks. Without it the manifest installer targets `claude`
+  and writes `.claude/skills/`.
+- `--with <id>` is repeatable and takes a **component** id from
+  `install-manifest.json` (`capability:mobx`, `framework:react`, …). It has no
+  single-skill form: the smallest unit the manifest installs is a module.
+  `review-pr-feedback` and the three `code-*` profile reviewers live in module
+  `review-core-skills`, which belongs to no component and arrives through a
+  profile that lists it (`core`, `full`).
+- Add `--dry-run` first to read the plan. A file already on disk that the
+  manifest installer did not write is left alone unless `--force` is passed.
+
+What to expect from the exit code:
+
+- **The manifest-installer forms can exit 1 after installing what was missing.**
+  `applyInstall` (`src/gdskills/manifest/apply.ts`) writes every planned file
+  whose destination is free, skips every planned file that already exists and
+  is not recorded in the manifest installer's install-state (or has drifted from
+  its recorded hash), and returns `ok: false` when it skipped anything;
+  `src/commands/skills.ts` turns that into exit 1. The legacy installer, which
+  `keryx init` uses, records no such state, so on a project it set up the output
+  is a `Wrote N file(s)` line for the missing skills, then a `Skipped (existing
+  file not recorded in install-state…)` list naming the skills already there,
+  then exit 1. Running the command again gives the same skip list and the same
+  exit code.
+- **Judge the outcome by the inventory, not the exit code.** Run
+  `keryx review reviewers --json`: with `bundledSource: "project"`, a skill in
+  the `bundled` half is installed. (`"package"` after an install means the
+  install did not write under `.metaproject/skills/gdskills/review` — check
+  `--target`.) If it is there, continue. If it is not, read the `Skipped` and `Errors` lines
+  for the skill's own path before doing anything else. `--force` makes the
+  installer overwrite the skipped files with the bundled copies, local edits
+  included, so it is the user's call, not a default retry.
+- **`keryx skills install --profile full` does not behave this way.** With no
+  manifest flag it takes the legacy route (`installGdskills`,
+  `src/gdskills/install.ts`), which copies each bundled skill directory over the
+  installed one without consulting install-state, and rewrites the project's
+  skills catalog and gdskills module manifest for the `full` profile. It sets
+  exit 1 only when `.metaproject/` is absent; a destination it will not write
+  through (a symlink, a non-directory) is listed under `Warnings` with exit 0.
+- **The dry-run's `Apply this plan:` hint is not the whole command.** It prints
+  only `--profile` and `--target`, so after a dry-run with
+  `--with capability:mobx` the hinted command installs the profile without
+  `code-mobx-store-review`. Re-type the command you dry-ran, minus `--dry-run`.
+
+Run `keryx review reviewers --json` again afterwards and dispatch from what it
+returns.
+
 ## CLI-engine reviewers — dispatched as a command, not a sub-agent
 
 `review-jev-rules` (flow 330), `review-jev-risk` and `review-jev-scenarios`

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

@@ -383,7 +383,7 @@ human or a bot has already reviewed pull request `#A`, and someone wants those
 comments interpreted, checked against the code, fixed and answered. Under its
 `--fix` mode it dispatches `flow-orchestrator`, which opens a **second** pull
 request `#B` carrying the fix, based on `#A`'s own head branch, and dispatches
-**this** orchestrator on every round against `#B`.
+**this** orchestrator on every round against `#B`. `review-pr-feedback` is present only when installed — it is in the `full` profile only. When it is absent no caller of this kind exists, so the default below holds and this orchestrator owns the reply; do not hand a request to it, say it is not installed and name the install command (`SKILL.detail.md`, "Skills present only when installed").
 
 `#B` is its own conversation. Collect and reply on it exactly as always: someone
 reviewing the fix deserves an answer from the run that made the fix, and its
@@ -1000,7 +1000,7 @@ Three bounds keep it from deleting coverage:
 
 - **Only path-triggered reviewers.** A reviewer selected by an explicit flag, or
   one whose scope is the whole change rather than a path set — `review-logic`,
-  `review-regression`, `review-verifier` — is never path-gated.
+  `review-regression`, `review-verifier` — is never path-gated. One exception, for project reviewers only: a flag that more than one project reviewer carries is a **family flag** (the inventory lists it in that reviewer's `familyFlags`). It selects the whole family, and each member stays path-gated — `--<family>` over a diff touching one member's paths dispatches that member, not all of them.
 - **Scope A only.** Scope B is the blast radius; it is *supposed* to name files the
   diff never touched.
 - **Ambiguity includes.** If you cannot decide whether a path matches, dispatch.
@@ -1024,7 +1024,7 @@ keryx review reviewers --json
 
 It returns two halves. `bundled` is the installed gdskills review tree — the set
 this project's install profile actually produced, which is not everything keryx
-ships. `project` is every project-skill under module `review`, living at
+ships — when `bundledSource` is `"project"`; when it is `"package"` the project has no installed review tree and the list is the keryx package's own (`SKILL.detail.md`, "Skills present only when installed"). `project` is every project-skill under module `review`, living at
 `.metaproject/project-skills/review/<name>/` so that it sits beside
 `.metaproject/skills/gdskills/review/<name>/` and needs no other marking.
 
@@ -1044,10 +1044,10 @@ Two things it does NOT get:
   the origin.
 
 **Select them with the fields the inventory returns, not by reading prose.**
-Each `project` entry carries `flags` (a passed flag selects it explicitly),
+Each `project` entry carries `flags` (a passed flag selects it) and `familyFlags` (the subset of `flags` another project reviewer also carries: a passed flag listed there selects it but leaves it path-gated; a passed flag in `flags` and not in `familyFlags` is unique to it, so it is explicit and ungated), `flagWarnings` (declared `metadata.flags` entries that were dropped as not being flags: they select nothing; name them once in the report),
 `paths` + `pathsSource` (the path gate; `none` → dispatch), `stackRequires`
 (stack scoping), `unresolvedRules` (dispatch, name the missing rules once in the
-report) and `drift` (dispatch, name it once in the report). What each means and
+report), `shadowedRules` (the dispatch prompt names each `resolved` file as the one to read in place of the `ref` the reviewer's own text spells), `unresolvedReferences` (dispatch, name them once in the report) and `drift` (dispatch, name it once in the report). What each means and
 what to do with it: `SKILL.detail.md` beside this file, section "Project-local
 reviewers". A description saying another entry point dispatches it is its
 author's routing note, not a restriction.
@@ -1085,7 +1085,7 @@ When `review.jev.select` is on, before Wave A/B dispatch: run `keryx review jev-
 
 ## Legacy/Profile Reviewer Auto-Detection
 
-Legacy/profile reviewers are specialized review profiles that predate the review-domain `review-*` naming. They are still valid and must be shown separately from generic and convention reviewers so the user can opt in deliberately.
+Legacy/profile reviewers are specialized review profiles that predate the review-domain `review-*` naming. They are still valid and must be shown separately from generic and convention reviewers so the user can opt in deliberately. **They are present only when installed:** `code-ai-review`, `code-learned-review`, `code-style-review` and `code-mobx-store-review` are in the `full` profile only, so in any other profile the flags below (`--code-ai`, `--learned`, `--code-style`, `--mobx-store`, `--legacy-profiles`) name reviewers that may not exist. When the inventory's `bundledSource` is `"project"`, a legacy reviewer missing from the `bundled` half of `keryx review reviewers --json` is absent (when it is `"package"` the half is the keryx package's own list and says nothing about this project — decide as `SKILL.detail.md`, "Skills present only when installed", describes): leave it out of the `Optional legacy/profile reviewers` preview, and when a flag asked for it, do not dispatch a substitute — record it in `Skipped reviewers` with reason `not-installed` and the command that adds it (`keryx skills install --profile full`, or the narrower manifest form in `SKILL.detail.md`, "Skills present only when installed"). `--legacy-profiles` and `--all` dispatch the legacy reviewers that are installed and skip the rest the same way.
 
 | Trigger | Reviewers appended |
 |---|---|
@@ -1289,18 +1289,18 @@ Before dispatching a reviewer through a platform-native sub-agent mechanism, ver
 
 Runtime rules:
 - If the exact reviewer agent type exists, dispatch that reviewer directly.
-- If the exact reviewer agent type does not exist but `skills/<reviewer>/SKILL.md` exists, dispatch `general-purpose` and include the reviewer name, skill path, bounded review context, and required `REVIEW_RESULT` schema in the prompt.
+- If the exact reviewer agent type does not exist but `skills/<reviewer>/SKILL.md` exists, dispatch `general-purpose` and include the reviewer name, the path of that skill file, bounded review context, and required `REVIEW_RESULT` schema in the prompt. For a bundled reviewer that path goes in the prompt text and in `dispatch_plan`, not in the input's `skill_path` field, which is for project reviewers only (the project-reviewer rule below).
 - If neither the agent type nor the skill file exists, do not silently substitute another reviewer. Mark that reviewer as `BLOCKED`, include the missing agent/skill name, and continue only with independent reviewers.
+- **A project reviewer is dispatched by its package, on every branch above.** For each entry in the `project` half of `keryx review reviewers --json`, put the absolute path of its registered `<path>/SKILL.md` in the dispatch (`skill_path`) and say in the prompt that this file is the reviewer's definition and overrides the built-in definition of any agent type with the same name. A runtime may ship an agent type called exactly what the project called its reviewer, carrying an older or unrelated prompt; without the path the round runs that prompt and reports it under the project reviewer's name. If the file is missing, mark the reviewer `BLOCKED` and name the missing path — do not fall back to the same-named agent type or to any other reviewer. For every entry in that reviewer's `shadowedRules`, the prompt also says which file to read: "where your text names `<ref>`, read `<resolved>` instead" (the absolute path of `resolved`). The project keeps its own version of that rule beside the one keryx ships under the same name, the reviewer's text still spells the shipped path, and nothing but this sentence in the dispatch makes it read the project's — see `SKILL.detail.md`, "Dispatching a project reviewer".
 - Record the chosen runtime per reviewer in `review_context.review_plan.dispatch_plan`.
-- The user-facing progress line must be explicit: "Running `<reviewer>` via `general-purpose` fallback because native agent type is unavailable."
-
-Do not use vague fallback messages such as "running through available agent types" without naming which reviewers used fallback and why.
+- The user-facing progress line must be explicit: "Running `<reviewer>` via `general-purpose` fallback because native agent type is unavailable." Do not use vague fallback messages such as "running through available agent types" without naming which reviewers used fallback and why.
 
 Pass each sub-reviewer a payload matching `.metaproject/skills/gdskills/review/review-orchestrator/reviewer-input.schema.json`:
 
 ```yaml
 review_context: <bounded context pack>
 reviewer: <skill-name>
+skill_path: <absolute path of <path>/SKILL.md — project reviewers only; omit for a bundled reviewer>
 scope_mode: diff | path
 context_doc: <path or empty>
 issue_url: <url or empty>

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

@@ -17,6 +17,13 @@
     "reviewer": {
       "type": "string"
     },
+    "skill_path": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "Absolute path of the reviewer's registered `<path>/SKILL.md`, set for every reviewer from the `project` half of `keryx review reviewers --json` and omitted for a bundled one. The file is the reviewer's definition: it overrides the built-in definition of a same-named agent type, whichever runtime branch dispatches it. A path that does not exist makes the reviewer BLOCKED, never substituted. Optional, and like the rest of this schema it is read by the dispatching agent — no keryx command validates a dispatch against it."
+    },
     "scope_mode": {
       "type": "string",
       "enum": [