@mrciphersmith/keryx 0.2.72 → 0.2.74

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrciphersmith/keryx",
-  "version": "0.2.72",
+  "version": "0.2.74",
   "description": "Version-controlled project context for AI coding agents: code graph, architecture wiki, project memory, relevant tests, quality signals, and task flows.",
   "private": false,
   "publishConfig": {
@@ -42,7 +42,7 @@
     "check": "tsc --noEmit && bun test",
     "check:doc-links": "bun scripts/check-doc-links.ts",
     "baseline:review-precision": "bun scripts/review-precision-baseline.ts",
-    "test:guards": "bun test src/lib/config-dir.ast.test.ts src/lib/config-dir.readers.test.ts src/lib/production-graph.test.ts src/harness/policy/profiles.test.ts src/lib/serve-server.test.ts"
+    "test:guards": "bun test src/lib/config-dir.ast.test.ts src/lib/config-dir.readers.test.ts src/lib/production-graph.test.ts src/harness/policy/profiles.test.ts src/lib/serve-server.test.ts src/gdskills/agent-catalogue-xref.test.ts src/gdskills/enforcement-claims.test.ts"
   },
   "files": [
     "dist",

package/src/gdskills/bundled/rules/core/gproject-contracts.mdc

@@ -33,7 +33,7 @@ Every dispatch from gproject-orchestrator MUST include:
 ```yaml
 # Required (from base protocol)
 description: "<phase>: <task>"
-subagent_type: "general"
+subagent_type: "general-purpose"
 prompt: "<structured prompt — see template below>"
 
 # gproject-specific (inside prompt)

package/src/gdskills/bundled/rules/core/jobs-documentation.mdc

@@ -80,7 +80,7 @@ Every job folder MUST contain at minimum:
     ...
 ```
 
-> **`results/` folder:** Created by `task-implementer` during Phase 6 (one file per task). The orchestrator and wave-executor never receive full task results inline — they read these files only when a task reports `DONE_WITH_CONCERNS` or `BLOCKED`. This keeps the orchestrator context bounded.
+> **`results/` folder:** Written by `task-implementer` during Phase 6.1 (one file per task), then validated with `keryx skills contracts validate … --schema task-implementer-output` and recorded with `keryx job document <job-name> --type implementation-report --file <that file>`, which refuses if the file was never written. There is no `wave-executor` agent: the orchestrator dispatches each task itself, never receives a full task result inline, and reads a `results/` file only when a task reports `DONE_WITH_CONCERNS` or `BLOCKED`. This keeps the orchestrator context bounded.
 
 ## README.md Format
 

package/src/gdskills/bundled/rules/core/subagent-context-construction.md

@@ -62,7 +62,7 @@ Use this template for every subagent dispatch:
 ```
 Task({
   description: "<one-line summary for logs>",
-  subagent_type: "general",
+  subagent_type: "general-purpose",
   prompt: |
     ## Task
     <Exactly what to do — no ambiguity>

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

@@ -0,0 +1,214 @@
+---
+name: reviewer-skill-creator
+model_tier: standard
+description: |
+  Use when asked to create a project-local reviewer for review-orchestrator, usually
+  from an existing source: a rules file, a review profile, a conventions doc, a
+  team's written review standard. Scaffolds the package under
+  .metaproject/project-skills/review/<name>/, records where the source came from
+  so drift is detectable later, writes the reviewer against the orchestrated review
+  contract, and confirms the orchestrator can see it.
+  NOT for: editing a bundled reviewer keryx ships (those live in the source tree and
+  change through a PR), and NOT for creating an ordinary entity project-skill
+  (entity-skill-creator).
+triggers:
+  - "create a reviewer"
+  - "new reviewer for review-orchestrator"
+  - "make a reviewer from this profile"
+  - "создай ревьюера"
+  - "создай нового ревьюера на основании"
+metadata:
+  author: "MrCipherSmith"
+  version: "1.0.0"
+  category: "core"
+  compatible_harnesses: "cursor,codex,zed,opencode,claude"
+license: "MIT"
+---
+
+# Reviewer Skill Creator
+
+Turn a written review standard into a reviewer the orchestrator will dispatch.
+
+The request usually arrives as one sentence — *"create a reviewer for
+review-orchestrator based on `<path>/rules/core/some-profile.mdc`"* — and it names two
+things: a **destination** (the review lane) and a **source** (a file someone
+else maintains). Both matter, and the second is the one that is usually
+mishandled.
+
+---
+
+## Where it goes, and why there
+
+```
+.metaproject/skills/gdskills/review/<name>/     <- reviewers keryx ships
+.metaproject/project-skills/review/<name>/      <- reviewers this project defines
+```
+
+The parallel is the whole convention. A project reviewer is a project-skill whose
+**module is `review`**; nothing else marks it, and `keryx review reviewers`
+finds it by that alone. Anyone who knows where bundled reviewers live knows where
+these go.
+
+---
+
+## Workflow
+
+```
+reviewer-skill-creator Progress:
+- [ ] Step 1: Read the source in full, and say what it is
+- [ ] Step 2: Scaffold the package, recording the source
+- [ ] Step 3: Write the reviewer against the orchestrated contract
+- [ ] Step 4: De-personalise
+- [ ] Step 5: Verify, and confirm the orchestrator sees it
+```
+
+### Step 1 — read the source in full, and say what it is
+
+Read the whole file before writing anything. A review profile is usually not
+organised as a reviewer: it is a list of rules, or a transcript of preferences,
+or a checklist mixed with examples from one specific repository.
+
+Sort what you find into three piles, out loud, in your reply:
+
+- **Method** — a way of establishing something. *Delete the gate and see whether
+  the suite stays green. Measure the rendered width. Read the producer at a
+  pinned SHA.* This is the valuable pile and it transfers.
+- **Convention** — a rule true of the source's own codebase. *Stores go in
+  `src/*/store.ts`.* Keep it only if it is true of THIS project; verify, do not
+  assume.
+- **Persona** — one person's voice, catchphrases, verdict vocabulary, and habits
+  of address. This pile is dropped whole. See Step 4.
+
+If the source is mostly the third pile, say so and stop. A reviewer distilled
+from someone's tone reviews tone.
+
+### Step 2 — scaffold the package, recording the source
+
+```bash
+keryx skills create "<short target>" \
+  --module review \
+  --name <reviewer-name> \
+  --note "<one line: what this reviewer is for>" \
+  --origin <path to the source file>
+```
+
+Three fields, three different jobs, and mixing them is the recorded failure mode:
+
+- `<short target>` is a **routing key** — a path, a symbol, or a short concept.
+  `keryx skills route` matches queries against it. Never a sentence.
+- `--note` is the prose. It renders under Purpose and touches nothing that routes.
+- `--origin` is the source file's path, stored verbatim and hashed. This is what
+  makes the next question answerable.
+
+**Always pass `--origin` when a source file exists.** The source is maintained
+somewhere else and will move on; without the hash, a reviewer built from last
+month's version reads as current forever, and nobody finds out until its findings
+disagree with the standard it claims to encode. With it,
+`keryx review reviewers` reports `drift: changed` the moment the file differs.
+
+Quote the path if it starts with `~` and you want it stored that way; an
+unquoted `~` is expanded by the shell before keryx sees it. Either is fine —
+both resolve — but the stored form is what a human reads later.
+
+### Step 3 — write the reviewer against the orchestrated contract
+
+The scaffold is a generic entity-skill template. Replace its body. A reviewer
+that does not conform is handled by the Sub-Agent Report Quality Gate exactly as
+a bundled one would be — local authorship is not evidence.
+
+Required, all of it in `SKILL.md`:
+
+- **Scope** — what this reviewer owns, and explicitly what it does not. Name the
+  neighbouring reviewers that own the excluded parts. A lane that does not say
+  where it stops duplicates three others.
+- **Checklist** — the method pile from Step 1, as checks that can be performed.
+- **Severity** — do **not** write a rubric. Point at
+  `review-orchestrator/SKILL.md` → **Severity (canonical)** and add one table
+  saying where this reviewer's recurring conditions land under it. Ten private
+  rubrics feeding one sort produce a ranking that means ten things at once.
+- **Shared laws** — copy the three verbatim from the orchestrator: no
+  unreproducible harm claim above `info`, never flag the theoretical, one finding
+  per class.
+- **Class scope** — `blocker` and `major` carry every site holding the shape and
+  the enumeration method that found them.
+- **Orchestrated Review Contract** — return `REVIEW_RESULT` per
+  `reviewer-finding.schema.json`, with a finding-id prefix of your own.
+
+If the source's method needs a command to be worth anything — a mutation, a
+measurement, a probe — say so as an iron law, and say what the finding is worth
+without it. A method nobody runs is a preference.
+
+### Step 4 — de-personalise
+
+Keep the method. Drop the person.
+
+Strip names and handles, catchphrases, verdict vocabulary, forms of address, and
+anything whose meaning depends on knowing the author. A rule that reads as one
+person's taste will be followed as taste; the same rule stated as a procedure
+with a stated reason will be followed as a procedure.
+
+This is not politeness, it is transferability, and keryx enforces the same line
+on its shipped tree: `bundled-eval.ts` fails a bundled skill that names the
+reviewer it was learned from or reuses their phrases. Project-skills are not
+scanned by that check — which makes this step your responsibility rather than
+the gate's.
+
+For every rule you keep, write the **reason** beside it. A reason survives being
+transplanted into a codebase the author never saw; an assertion does not.
+
+### Step 5 — verify, and confirm the orchestrator sees it
+
+```bash
+keryx skills verify review/<reviewer-name>
+keryx review reviewers
+```
+
+The second is the one that matters: it is the same call
+`review-orchestrator` makes, so its output is proof the reviewer will be
+dispatched rather than a hope. Check the row shows your reviewer with
+`drift: clean`.
+
+Then say, in your reply, which of the three piles from Step 1 you kept, which you
+dropped, and what you could not verify against this project.
+
+---
+
+## Iron Laws
+
+1. **`--origin` whenever a source file exists.** A reviewer built from a file
+   nobody can trace back is a reviewer nobody can update.
+2. **The target is a routing key, the note is the prose.** A sentence in the
+   target produces a skill that matches no query and verifies as permanently
+   stale. This is a recorded failure, not a hypothetical.
+3. **No private severity rubric.** Point at the canonical one.
+4. **Drop the persona, keep the method, state the reason.**
+5. **Do not claim the reviewer is wired until `keryx review reviewers` shows
+   it.** Creating files is not registration, and registration is not discovery.
+
+---
+
+## Refreshing a reviewer whose source moved on
+
+`keryx review reviewers` reporting `drift: changed` means the source file differs
+from what was imported. It does **not** mean the reviewer is wrong.
+
+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.
+
+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.
+
+---
+
+## Scope Boundaries
+
+| Concern | This skill | Use instead |
+|---|---|---|
+| Create a project-local reviewer | YES | — |
+| Refresh one whose origin drifted | YES | — |
+| Create an entity/module project-skill | NO | `entity-skill-creator` |
+| 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` |

package/src/gdskills/bundled/skills/orchestration/code-verifier/SKILL.codex.md

@@ -1,47 +1,353 @@
 ---
 name: code-verifier
-description: "Full quality gate: lint, type-check, tests, circular imports. Mandatory post-implementation step in job-orchestrator. Use when: verifying code after implementation, running quality gate before review, checking code health standalone."
+model_tier: light
+description: "Use when running a full quality gate after implementation — lint, type-check, tests, and import validation. Mandatory step in job-orchestrator after task-implementer and after fix iterations. Use standalone when you need a structured verification report."
 triggers:
   - "Run verification"
   - "Quality gate"
+  - "Check code quality"
   - "Run lint and tests"
   - "Verify implementation"
+  - "Run checks"
 metadata:
   author: "MrCipherSmith"
   version: "1.0.0"
   category: "verification"
+  agent_worthy: true
   compatible_harnesses: "cursor,codex,zed,opencode"
 license: "MIT"
 ---
 
 # Code Verifier
 
-Full quality gate: lint → type-check → tests → circular imports.
+## Purpose
 
-**Position:** task-implementer → **code-verifier** → review
+Runs the full quality gate for a project: lint, type-check, tests, and import validation. Provides a structured, parseable result that the orchestrator uses to decide whether to proceed or trigger a fix loop.
 
-## Steps
-1. Detect PM and tooling (bun/npm/pnpm/yarn/python/go)
-2. Run lint (ESLint/Biome/ruff)
-3. Run type-check (tsc --noEmit / mypy / pyright)
-4. Run tests (vitest/jest/pytest/go test)
-5. Check circular imports (madge, if available)
-6. Classify findings by severity, determine gate
-7. Emit VERIFICATION_RESULT
+**Distinct from `task-implementer` Phase 5:** task-implementer does inline self-verification during implementation. `code-verifier` is an independent gate that runs after all tasks in a wave are complete — giving a clean, consolidated view of the whole diff, not per-task.
 
-## Gate
-- CRITICAL (type errors, test failures) or HIGH (lint errors, cycles) → GATE: FAIL
-- LOW only → GATE: PASS_WITH_WARNINGS
+**Input:** Codebase path + worktree path + scope (changed files or full project)
+**Output:** `VERIFICATION_RESULT` structured report — gate status (pass/fail), per-check results, actionable findings
+
+## When to Use
+
+- Dispatched by `job-orchestrator` after each task-implementer wave (mandatory)
+- Dispatched by `job-orchestrator` after each fix iteration
+- Run standalone: "verify my code", "run quality gate", "/code-verifier"
+- Any time you need a reproducible, structured view of project health
+
+## Architecture: 4 Phases
+
+```
+Phase 1: DETECT   →  Auto-detect stack, tooling, commands
+Phase 2: RUN      →  Execute lint → type-check → tests → import-check
+Phase 3: ANALYZE  →  Parse outputs, classify findings by severity
+Phase 4: REPORT   →  Emit VERIFICATION_RESULT
+```
+
+---
+
+## Workflow
+
+```
+Code Verifier Progress:
+- [ ] Phase 1: Detect stack and tooling
+- [ ] Phase 2: Run verification checks
+- [ ] Phase 3: Analyze and classify findings
+- [ ] Phase 4: Report results
+```
+
+---
+
+### Phase 1: DETECT
+
+Auto-detect the project stack and available verification tools.
+
+**1.1 Package manager and runner:**
+
+```bash
+cd <codebase_path>
+
+if   [ -f bun.lockb ];         then PM=bun;    RUNNER="bun run"
+elif [ -f pnpm-lock.yaml ];    then PM=pnpm;   RUNNER="pnpm run"
+elif [ -f yarn.lock ];         then PM=yarn;   RUNNER="yarn"
+elif [ -f package-lock.json ]; then PM=npm;    RUNNER="npm run"
+elif [ -f pyproject.toml ] || [ -f requirements.txt ]; then PM=python; RUNNER=""
+elif [ -f go.mod ];            then PM=go;     RUNNER=""
+else PM=unknown; RUNNER=""
+fi
+```
+
+**1.2 Detect available check commands:**
+
+| Check | How to detect | Command |
+|---|---|---|
+| Lint | `package.json` has `"lint"` script | `$RUNNER lint` |
+| Lint (auto) | `eslint.config.*` or `.eslintrc*` present | `npx eslint . --max-warnings 0` |
+| Biome | `biome.json` present | `npx biome check .` |
+| Type-check | `package.json` has `"type-check"` or `"typecheck"` script | `$RUNNER type-check` |
+| Type-check (auto) | `tsconfig.json` present | `npx tsc --noEmit` |
+| Tests | `package.json` has `"test"` script | `$RUNNER test --run` (vitest) or `$RUNNER test` |
+| pytest | `pytest` in `pyproject.toml` or `requirements.txt` | `pytest --tb=short -q` |
+| Go tests | `go.mod` present | `go test ./...` |
+| Circular imports | `madge` in devDependencies | `npx madge --circular src/` |
+
+**1.3 Determine scope:**
+
+```
+IF scope = "changed" (default when dispatched by orchestrator):
+  FILES = git diff --name-only <base_branch>...HEAD
+  Run tests only for files related to changed code
+  Run lint only on changed files: npx eslint <changed_files>
+  Run type-check on full project (tsc doesn't support file-level scope)
+
+IF scope = "full":
+  Run all checks on full project
+```
+
+**Output of Phase 1:**
+```
+TOOLING:
+  pm: bun | pnpm | yarn | npm | python | go | unknown
+  runner: "bun run" | ...
+  checks_available: [lint, type-check, tests, circular-imports]
+  checks_skipped: [<reason>]
+  scope: changed | full
+  changed_files: [<paths>]
+```
+
+---
+
+### Phase 2: RUN
+
+Execute each available check in order. Capture full output.
+
+**Execution order:** lint → type-check → tests → import-check
+
+**Do NOT abort early** — run all checks even if one fails. The orchestrator needs the complete picture.
+
+**2.1 Lint:**
+```bash
+# Changed files only (faster, more actionable)
+npx eslint <changed_files> --format=json --max-warnings 0
+# OR if lint script exists:
+$RUNNER lint
+```
+
+Capture:
+- Exit code (0 = pass, non-zero = fail)
+- Number of errors and warnings
+- Per-file error list (file path, line, column, rule, message)
+
+**2.2 Type-check:**
+```bash
+npx tsc --noEmit 2>&1
+# OR:
+$RUNNER type-check
+```
+
+Capture:
+- Exit code
+- Number of errors
+- Per-error: file, line, column, message, TS error code
+
+**2.3 Tests:**
+```bash
+$RUNNER test --run 2>&1        # vitest
+# OR: npx jest --ci 2>&1
+# OR: pytest --tb=short -q 2>&1
+# OR: go test ./... 2>&1
+```
+
+Capture:
+- Exit code
+- Tests passed / failed / skipped counts
+- Per-failure: test name, file, error message, stack (first 5 lines)
+
+**2.4 Circular import check (if madge available):**
+```bash
+npx madge --circular --extensions ts,tsx src/ 2>&1
+```
+
+Capture:
+- Exit code
+- List of circular chains (if any)
+
+---
+
+### Phase 3: ANALYZE
+
+Parse raw outputs into structured findings. Classify by severity.
+
+**3.1 Severity classification:**
+
+| Finding | Severity |
+|---|---|
+| Type error | CRITICAL |
+| Test failure | CRITICAL |
+| ESLint error (not warning) | HIGH |
+| Circular import | HIGH |
+| ESLint warning | LOW |
+| Skipped test | INFO |
+
+**3.2 Gate decision:**
+
+```
+GATE = PASS
+IF any CRITICAL findings  → GATE = FAIL (blocks proceed)
+IF any HIGH findings      → GATE = FAIL (blocks proceed)
+IF only LOW/INFO findings → GATE = PASS_WITH_WARNINGS
+```
+
+**3.3 Actionable finding format:**
+
+Each finding must include enough context for `task-implementer` (fix mode) to resolve it without re-reading the full output:
+
+```
+{
+  severity: CRITICAL | HIGH | LOW | INFO,
+  check: lint | type-check | test | circular-import,
+  file: <path>,
+  line: <N> | null,
+  column: <N> | null,
+  rule: <ESLint rule or TS error code> | null,
+  message: <error text>,
+  suggestion: <optional fix hint>
+}
+```
+
+---
+
+### Phase 4: REPORT
+
+Emit the structured `VERIFICATION_RESULT` as the final message.
 
-## Output
 ```
 VERIFICATION_RESULT:
   gate: PASS | PASS_WITH_WARNINGS | FAIL
-  checks: { lint, type_check, tests, circular_imports }
-  findings: [{ severity, check, file, line, rule, message }]
-  summary: "..."
+  scope: changed | full
+  
+  checks:
+    lint:
+      status: pass | fail | skipped
+      errors: <N>
+      warnings: <N>
+      command_used: "<command>"
+    
+    type_check:
+      status: pass | fail | skipped
+      errors: <N>
+      command_used: "<command>"
+    
+    tests:
+      status: pass | fail | skipped
+      passed: <N>
+      failed: <N>
+      skipped: <N>
+      command_used: "<command>"
+    
+    circular_imports:
+      status: pass | fail | skipped
+      cycles: <N>
+  
+  findings:
+    - severity: CRITICAL
+      check: type-check
+      file: src/services/UserService.ts
+      line: 42
+      rule: TS2345
+      message: "Argument of type 'string' is not assignable to parameter of type 'number'"
+    - severity: HIGH
+      check: lint
+      file: src/components/Form.tsx
+      line: 18
+      rule: "no-unused-vars"
+      message: "'value' is defined but never used"
+  
+  summary: "<1-2 sentence human-readable summary>"
+```
+
+**STATUS reporting:**
+
+```
+STATUS: DONE          — gate PASS or PASS_WITH_WARNINGS, report follows
+STATUS: DONE_WITH_CONCERNS — PASS_WITH_WARNINGS with notable warnings
+STATUS: BLOCKED       — could not run checks (missing tooling, wrong directory)
+```
+
+> If `gate: FAIL` → STATUS is still `DONE` (the gate result, not the skill's execution). The orchestrator reads `gate: FAIL` and decides to trigger fix.
+
+---
 
-STATUS: DONE
+## Integration with job-orchestrator
+
+The orchestrator dispatches `code-verifier` at two points:
+
+**After task-implementer wave (pre-review gate):**
 ```
+code-verifier:
+  codebase_path: <worktree_path>
+  scope: changed
+  base_branch: <base_branch from JOB_STATE>
+→ If gate: FAIL → dispatch fix tasks → re-run code-verifier
+→ If gate: PASS → proceed to review
+```
+
+**After fix iterations (post-fix gate):**
+```
+code-verifier:
+  codebase_path: <worktree_path>
+  scope: changed
+→ If gate still FAIL after 2 iterations → report as BLOCKED, skip to report
+→ If gate: PASS → proceed to report
+```
+
+**The orchestrator's internal "checks" step (2.8) is replaced by `code-verifier` dispatch.**
+
+---
+
+## Standalone Usage
+
+```bash
+# Run on current directory, changed files only
+/code-verifier
+
+# Run on specific project
+/code-verifier --path /path/to/project
+
+# Full project scan (not just changed files)
+/code-verifier --scope full
+```
+
+---
+
+## Automation Settings
+
+| Setting | Default | Options | Description |
+|---------|---------|---------|-------------|
+| `scope` | `changed` | `changed` / `full` | Limit checks to changed files or run full project |
+| `fail_on_warnings` | `false` | true/false | Treat ESLint warnings as gate failures |
+| `include_circular` | `true` | true/false | Run circular import detection if madge available |
+| `max_findings_reported` | `20` | 1-100 | Cap findings in report to avoid overflow |
+
+---
+
+## Error Handling
+
+| Error | Action |
+|---|---|
+| Check command not found | Mark check as `skipped`, continue others |
+| Wrong working directory | ABORT with `STATUS: BLOCKED` and directory hint |
+| Command times out (>120s) | Mark check as `skipped (timeout)`, continue |
+| Zero checks available | `STATUS: BLOCKED` — cannot verify without any tooling |
+| Circular import tool missing | Skip silently (not installed in all projects) |
+
+---
+
+## Rules of Engagement
 
-Full spec: `.metaproject/skills/gdskills/orchestration/code-verifier/SKILL.md`
+1. **Run ALL checks** — never abort after first failure. The orchestrator needs the full picture.
+2. **Do NOT modify files** — this is read-only verification.
+3. **Scope to changed files** by default — full scans are slow and produce noise.
+4. **Be specific** in findings — include file, line, rule, message. Vague "lint failed" is not actionable.
+5. Return `VERIFICATION_RESULT` as the **final message** to the orchestrator.