@mrciphersmith/keryx 0.3.85 → 0.3.87

package/dist/core.js

@@ -9995,7 +9995,6 @@ var init_route_tokens = __esm(() => {
     "them"
   ]);
 });
-
 // src/gdskills/skill-frontmatter.ts
 function frontmatterLines(content) {
   const text = content.startsWith("\uFEFF") ? content.slice(1) : content;
@@ -10791,12 +10790,12 @@ var init_skill_length_ceilings = __esm(() => {
     "orchestration/flow-orchestrator": 694,
     "orchestration/issue-analyzer": 373,
     "orchestration/job-documenter": 414,
-    "orchestration/job-orchestrator": 2243,
+    "orchestration/job-orchestrator": 2235,
     "orchestration/task-implementer": 668,
     "planning/autodoc-analyst": 180,
     "planning/autodoc-architect": 179,
     "planning/autodoc-assembler": 145,
-    "planning/autodoc-orchestrator": 343,
+    "planning/autodoc-orchestrator": 342,
     "planning/autodoc-scanner": 183,
     "planning/autodoc-writer": 270,
     "planning/brainstorm": 115,
@@ -10853,7 +10852,7 @@ var init_skill_length_ceilings = __esm(() => {
     "review/review-jev-scenarios": 187,
     "review/review-layout": 238,
     "review/review-logic": 377,
-    "review/review-orchestrator": 1712,
+    "review/review-orchestrator": 1614,
     "review/review-performance": 374,
     "review/review-pr-feedback": 895,
     "review/review-regression": 216,
@@ -11732,7 +11731,8 @@ var init_tools = __esm(() => {
     "apply_patch",
     "shell_exec",
     "web_fetch",
-    "web_search"
+    "web_search",
+    "spawn_subagent"
   ];
   TOOL_TARGET_MAPS = {
     claude: new Map([
@@ -25505,6 +25505,10 @@ function dispatchErrors(value) {
       errors.push(`${role}: missing or shared execution identity`);
     if (text(run.executionId))
       executions.add(run.executionId);
+    if (run.status === "not-run") {
+      errors.push(`${role}: not run${text(run.notRunReason) ? ` (${run.notRunReason})` : ""}; a reviewer that did not run is never a clean pass`);
+      continue;
+    }
     if (run.status !== "complete" || run.scopeComplete !== true)
       errors.push(`${role}: reviewer scope is incomplete`);
     if (!text(run.rawEvidence))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrciphersmith/keryx",
-  "version": "0.3.85",
+  "version": "0.3.87",
   "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": {

package/src/gdskills/bundled/skills/orchestration/flow-orchestrator/SKILL.md

@@ -21,6 +21,10 @@ license: "MIT"
 
 # Flow Orchestrator
 
+## Preflight
+
+Run in the main session: this skill dispatches workers. Without the `Agent` tool, or with the depth budget spent (Claude Code nests at most 3 deep), the whole output is this line, with no tool calls and no work of your own: `STATUS: BLOCKED nested_dispatch_unavailable — run this skill in the main session`
+
 ## Purpose
 
 Flow Orchestrator is the Task Manager-aware implementation orchestrator. Plan bridge: publish the tasks with `plan_set` under the ids `T1`…`Tn`, mirror each `keryx flow task done` with `plan_update`, and publish Phase 4's completion choice as `proposed` — see the `session-plan-bridge` rule.
@@ -28,8 +32,6 @@ It wraps the existing gdskills pipeline with `keryx flow` state.
 
 Use this skill instead of `job-orchestrator` when the user wants a managed story/issue lifecycle with frozen acceptance criteria, task state, an explicit completion choice, Code Health, and a durable flow package in `.metaproject/flows/`.
 
-Do not modify `job-orchestrator` or `task-implementer` behavior. They remain usable without Task Manager. This skill coordinates them through flow state.
-
 ## Hard Preconditions
 
 1. Read `.metaproject/index.md` and `.metaproject/metaproject.json`.
@@ -122,9 +124,8 @@ it already tried. The flow package does.
       keryx flow next <id> --json
       ```
 
-      This is the first task whose `status` is not `done` and whose declared
-      `dependsOn` are all `done` — the ordering computed from the package
-      instead of re-derived by you from prose.
+      This is the first task not `done` whose declared `dependsOn` are all
+      `done` — computed from the package, not re-derived from prose.
 
    4. **Read the `resume` field before dispatching anything.** It has three
       answers and they are not interchangeable:
@@ -141,10 +142,9 @@ it already tried. The flow package does.
         or close the task (`keryx flow task done <id> <Tn>`). Re-dispatching
         over an unresolved attempt is how the same work gets done twice.
 
-      `keryx flow next` also lists every OTHER not-done task carrying an
-      unresolved attempt, under `unresolved`. Those are parallel dispatches that
-      never reported back; resolve them the same way before assuming the flow is
-      idle.
+      `keryx flow next` also lists every OTHER not-done task with an unresolved
+      attempt, under `unresolved`: parallel dispatches that never reported back.
+      Resolve them the same way before assuming the flow is idle.
 
    5. Before dispatching a worker for that task, record the attempt:
 
@@ -436,19 +436,17 @@ Before accepting implementation:
 4. Check the bounds, then run `review-orchestrator` with relevant domains — in this session,
    never handed whole to one subagent: one without a dispatch tool returns `STATUS: BLOCKED`.
    ```bash
-   keryx review budget --spent <usd-so-far> --outstanding <subagents you already have in flight>
+   keryx review budget --spent <usd-so-far> --full --outstanding <subagents still running, 0 if none>
    ```
    A non-zero exit means the spend ceiling (3 USD by default) has been reached:
    **stop and ask the user** rather than dispatching another fan-out — never shrink the fan-out to fit.
    Dispatch prompts point at sources (files, SHAs, the PR) and never paraphrase a contract.
 
-   `--outstanding` is the part that matters here. `review-orchestrator`
-   dispatches reviewers in parallel and runs *nested* under this skill, and
-   keryx cannot observe subagents in another process. Passing the count you
-   already have in flight is the only thing that makes the concurrency cap mean
-   anything across the nesting; omit it and the cap bounds the reviewer fan-out
-   alone, which the review record then states plainly rather than implying
-   otherwise.
+   `--outstanding` is the part that matters here. `review-orchestrator` runs inline
+   in this session and dispatches reviewers in parallel; keryx cannot observe other
+   subagents. Passing the count still running is the only thing that makes the
+   concurrency cap mean anything; omit it and the cap bounds the reviewer fan-out
+   alone, which the review record then states plainly. Add `--full` for `--all`.
 
 5. If findings require code changes, dispatch fix work through `task-implementer`
    and record the fix task in the flow.
@@ -586,7 +584,9 @@ the bound plus an escalation — never an unbounded loop.
    findings, affected graph, relevant wiki, and health/testing artifacts;
    identify the likely cycle cause; choose a materially different fix strategy
    or split the work into narrower tasks; record the decision in `journal.md`;
-   then continue with the enriched context.
+   then continue with the enriched context. The review round count is not reset:
+   past `REVIEW_ROUND_CAP` rounds on one merge-base..HEAD, report to the operator
+   instead of running another round.
 6. Never merge while findings or required checks remain unresolved. If the
    re-planned approach still cannot produce a mergeable PR, leave the flow
    `in-progress` and report the blocker instead of forcing completion.

package/src/gdskills/bundled/skills/orchestration/job-orchestrator/SKILL.md

@@ -22,14 +22,12 @@ metadata:
 license: "MIT"
 ---
 
-<SUBAGENT-STOP>
-If you were dispatched as a subagent to execute a specific task, skip this skill entirely.
-This skill is for orchestrators and interactive session-level routing only.
-Proceed directly with your assigned task.
-</SUBAGENT-STOP>
-
 # Job Orchestrator
 
+## Preflight
+
+Run in the main session: this skill dispatches sub-agents. Without the `Agent` tool, or with the depth budget spent (Claude Code nests at most 3 deep), the whole output is this line, with no tool calls and no work of your own: `STATUS: BLOCKED nested_dispatch_unavailable — run this skill in the main session`
+
 ## Purpose
 
 Dynamic orchestrator that builds execution plans based on user intent. Unlike a fixed pipeline, the orchestrator adapts its workflow to what the user actually needs — from "just analyze this issue" to "implement, review, and create a PR". It dispatches sub-agents (`issue-analyzer`, `context-collector`, `tests-creator`, `task-implementer`, `code-verifier`, `review-orchestrator`) and persists every step, document and retry through `keryx job`, which writes `.metaproject/jobs/<job-name>/`. Plan bridge: publish these steps with `plan_set` under the ids `keryx job status` reports, mirror each `keryx job step` with `plan_update`, and mark them `proposed` while the approval above is open — see the `session-plan-bridge` rule.
@@ -1059,16 +1057,14 @@ carried in the dispatch prompt and reported in 2.9.
 **Step 1 — check the budget before dispatching, while stopping is still possible.**
 
 ```bash
-keryx review budget --spent <usd-so-far> --outstanding <subagents this orchestrator has in flight>
+keryx review budget --spent <usd-so-far> --full --outstanding <subagents still running, 0 if none>
 ```
 
-`--outstanding` is not optional here. `src/review/caps.ts` names `job-orchestrator`
-as the outermost of the three nesting levels — `job-orchestrator` →
-`flow-orchestrator` → `review-orchestrator` — that its cap of 4 in-flight reviewers
-was chosen to survive. keryx is a CLI invoked once per command; it cannot observe
-subagents running inside another orchestrator's process. **The cap binds the nested
-total only when the parent declares its own in-flight count.** Omit `--outstanding`
-and the cap bounds the reviewer fan-out alone, which the record then states plainly.
+`--outstanding` is the number of subagents this session still has running while the
+round starts (0 when none). All three orchestrators run inline in the main session, so the
+reviewers are the only fan-out; keryx cannot observe other subagents, so **the wave size
+(at most 10 for `--all` or a full review; add `--full`) binds the total only when you
+declare that count.** Omit it and the record states that the cap bounds the reviewers alone.
 
 A non-zero exit means the spend ceiling (3 USD by default) is reached: stop and ask
 the user rather than dispatching another fan-out.
@@ -1122,30 +1118,26 @@ replaced. The command names no model — it ranks what the provider reports at r
 and, when it cannot rank anything, prints `inherit: true`, which means the dispatch
 runs on the session model. That is a correct answer, not a failure.
 
-**Step 6 — dispatch `review-orchestrator`.**
+**Step 6 — run `review-orchestrator` inline, in this main session.** Load
+`skills/gdskills/review/review-orchestrator/SKILL.md` yourself; do **not** wrap it in a
+`Task` — a subagent cannot spawn the reviewers and the skill answers
+`STATUS: BLOCKED nested_dispatch_unavailable`. Give it these inputs:
 
 ```
-Task({
-  description: "Review round <n>: <job-name>",
-  subagent_type: "general-purpose",
-  prompt: |
-    Load skill: skills/gdskills/review/review-orchestrator/SKILL.md
-
-    flags:            <selected flags, e.g. --backend --security --testing-practices>
-    commit_range:     <BASE_SHA>..HEAD
-    issue_url:        <issue URL, when the job has one — enables the Stage 1 spec gate>
-    context_doc:      <JOBS_ROOT>/<job-name>/ai/context.md
-    verification_mode: annotate
-    managed_review:   { mode: "review-flow", target: "branch", target_ref: "<feature-branch>" }
-    is_fix_round:     <true on any round after the first>
-    pr_comments:      { enabled: <true when a PR exists> }
-
-    Emit the unified report AND the fenced ```json keryx:findings``` block.
-    Dispatch review-verifier (Wave C) over the consolidated findings and return
-    its verification claims as a file path.
-})
+flags:             <selected flags, e.g. --backend --security --testing-practices>
+commit_range:      <BASE_SHA>..HEAD
+issue_url:         <issue URL, when the job has one — enables the Stage 1 spec gate>
+context_doc:       <JOBS_ROOT>/<job-name>/ai/context.md
+verification_mode: annotate
+managed_review:    { mode: "review-flow", target: "branch", target_ref: "<feature-branch>" }
+is_fix_round:      <true on any round after the first>
+pr_comments:       { enabled: <true when a PR exists> }
 ```
 
+It emits the unified report AND the fenced ```json keryx:findings``` block, and runs
+`review-verifier` (Wave C) over the consolidated findings, returning its verification
+claims as a file path.
+
 **Step 7 — verification is part of the round, not an extra.** `review-orchestrator`
 dispatches `review-verifier` in Wave C over the consolidated findings. The verifier
 **runs something** and can only delete — it never raises a severity, adds a finding,
@@ -1310,7 +1302,7 @@ FOR iteration in [1, 2, 3]:
        keryx review comments collect --repo <r> --pr <n> --sha <new-head> --round <N+1> --out <file>
        keryx review scope        --ref "$BASE_SHA" --json > scope.json
        keryx review blast-radius --ref "$BASE_SHA" --previous blast-radius.json --json > blast-radius.json
-       <dispatch review-orchestrator with is_fix_round: true>
+       <run review-orchestrator inline, in this session, with is_fix_round: true>
        keryx review ingest  --report <new-report> --ref <feature-branch> --head <new-head> \
                             --scope scope.json --blast-radius blast-radius.json \
                             --verifications <file> --refuted <file> --outstanding <n>
@@ -1985,7 +1977,7 @@ What actually bounds this orchestrator:
 | review → fix rounds | 3 | 2.7, and `max_review_iterations` (`maximum: 3`) in the input contract |
 | repetition, whatever the count says | first repeat | the STUCK CHECK in 2.7, and `keryx review loop` against the durable record |
 | retries per step | recorded, not guessed | `metrics.steps[].retries`, incremented by `keryx job step --status in-progress` and read back with `keryx job status --json` |
-| reviewer fan-out | 4 in flight | `keryx review budget --outstanding <n>` before every dispatch (2.6.1) |
+| reviewer fan-out | ≤10 per wave | `keryx review budget --outstanding <n>` before every dispatch (2.6.1) |
 | spend | 3 USD by default | `keryx review budget --spent <usd>` — a non-zero exit means stop and ask |
 
 Each of these is a number some command reads or writes. A guard no command can

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

@@ -20,8 +20,7 @@ metadata:
   version: 1.0.0
 ---
 
-<!-- SUBAGENT-STOP: If you are a subagent dispatched by another orchestrator, HALT.
-     Return STATUS: BLOCKED — autodoc-orchestrator must run as top-level agent only. -->
+**Preflight:** run in the main session. Without the `Agent` tool or depth budget, output only `STATUS: BLOCKED nested_dispatch_unavailable — run this skill in the main session`, with no tool calls.
 
 # autodoc-orchestrator
 

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

@@ -426,7 +426,7 @@ re-request after fixes. A gating round runs the composition the start questions
 selected.
 
 - **No dispatch tool, no review.** A host that cannot dispatch subagents — this
-  engine running inside a subagent is the usual case — returns
+  engine running inside a subagent, say — returns
   `STATUS: BLOCKED` with reason `nested_dispatch_unavailable` and no verdict.
   It does not review the diff alone and call that a round. Measured (flow 405):
   a single-agent round on a 150-line frontend PR wrote "did not dispatch any
@@ -503,3 +503,173 @@ New managed packages carry `research.json`, initially pending. Before closing a
 Supply the ledger using `keryx review ingest --research <ledger.json>` alongside the report and findings. Format: `version: 1`, `scopeReviewed: true`, `rawReconciled: true`, `obligations: [...]`. Each obligation requires `id`, `source`, `question`, `status`, `evidence`, `reason`. Status `finding` additionally requires `finding` pointing to exactly one canonical finding ID or global ID. Other terminal statuses are `refuted` and `out-of-scope`, both requiring evidence and reason. Preserve distinct scenarios when deduplicating. Assert census/reconciliation flags only after performing those checks; an empty obligations array is valid only if the actual census found no open observations.
 
 Open, deferred and unverifiable obligations block completion. If context, runtime or budget prevents resolution, retain the obligation and report incomplete; do not relabel it refuted or out-of-scope. Completion and the flow gate re-read the ledger even when the manifest says closed. Legacy packages without this artifact remain compatible, not proven complete. This gate validates the declared ledger, not the truth or exhaustiveness of its census; independent source/raw audits remain necessary.
+
+## Why Wave C verifies instead of re-scoring
+
+Wave C used to run `review-strict`: a meta-pass that re-read the consolidated
+findings and **adjusted their severity with no new evidence**, under an elevation
+table biased 3:1 toward escalation. It was **removed, not improved**, and the
+reason is measured rather than stylistic:
+
+- **GPT-4 on GSM8K across self-correction rounds: 95.5 → 91.5 → 89.0.**
+  **GPT-3.5 on CommonSenseQA: 75.8 → 38.1.** Among the answers that changed,
+  correct → incorrect exceeded incorrect → correct (Huang et al., *Large Language
+  Models Cannot Self-Correct Reasoning Yet*, ICLR 2024, arXiv:2310.01798).
+- **Self-Refine (arXiv:2303.17651): +49.2 on dialogue response generation, +0.2
+  on maths.** Self-refinement gains are on subjective tasks and vanish on
+  verifiable reasoning. Judging whether a null-guard is missing is verifiable
+  reasoning.
+
+Re-scoring a finding by re-reading it is therefore not a rigour pass; it is a
+coin flip weighted toward more findings. **Do not restore it because it looks
+obviously useful — it looked obviously useful the first time.**
+
+`review-verifier` occupies the slot and differs in exactly one way that matters:
+**it runs something.** Verification that executes rejects 85–96% of false reports
+against 4–15% unaided while finding 30–44% more true bugs (AnyPoC,
+arXiv:2604.11950); Meta's TestGen-LLM funnel discards 75% of its own output
+(75% build → 57% build and pass → 25% improve coverage) and the surviving quarter
+reaches 73% human acceptance (arXiv:2402.09171).
+
+## Scope B — bounds, rejections and recompute
+
+It walks `gdgraph affected` outward from every changed file, ranks by edge
+distance, keeps distance ≤ 2, cuts at 40 files closest-first, and adds a changed
+file's naming-related tests when the graph did not already reach them. Requires a
+built graph — run `keryx gdgraph build` if it refuses.
+
+**Do not pick the files yourself, and do not widen it.** "Review the
+functionality so nothing breaks" naively means "review the whole repository every
+round", which is unaffordable *and* actively harmful: review quality decays as
+context grows — measured F1 0.65 at round 2 falling to 0.29 at round 10. An
+unbounded scope B makes later rounds worse than earlier ones.
+
+The bounds are measured on this repository, not guessed: at depth 2 the set is a
+median of 19 files (p90 65); depth 3 buys eight more in the median and doubles
+the p90. The 40-file cap fires on 25% of commits and removes only hop-2 entries
+on all but 2 of 80, so it almost never costs a direct dependent — and when it
+does, it says so.
+
+**Record the whole thing.** `--out "<review-package>/blast-radius.md"` writes the
+set, the depth, and **every file the cap removed**. A truncation nobody can see
+reads afterwards as "we checked everything", which is the claim this pipeline
+exists to stop making. An empty radius is reported as `unresolved`, not as clean:
+the graph indexes code, so a change to a skill, a rule or a schema has no blast
+radius at all and that is a different fact from "nothing depends on it".
+
+### The scope-B question, and what is rejected
+
+> Does this change break an existing behaviour **at these sites**?
+
+Nothing else. The blast-radius set is **under regression check, not under
+review**. A finding about style, naming or architecture in code the change did
+not touch is refused **by the orchestrator in code** — not discouraged here —
+under three rules, every one of them a fact about the claim rather than about who
+made it:
+
+| Rule | Refused because |
+|---|---|
+| `outside-set` | the file is neither in the computed set nor in the changed set; the reviewer went browsing |
+| `non-regression-severity` | below `major`. Under the canonical rubric `minor` states the code behaves correctly and `info` names neither trigger nor outcome; neither can be a claim that something broke |
+| `no-link-to-change` | nothing in the finding names a changed file, module or symbol. A regression claim says THE CHANGE broke this site |
+
+Rejections are **recorded, not deleted** — raise the observation under scope A or
+as a separate review. Pass `--brief` output verbatim into the scope-B dispatch:
+the code rejection is the enforcement, but a reviewer told afterwards has already
+spent the round producing findings that will all be refused.
+
+`class_scope` on a scope-B finding names the **caller that breaks**, not the
+changed line, because that is the site a human has to look at.
+
+### When it is recomputed
+
+| Round | Scope A | Scope B |
+|---|---|---|
+| 1 (first after the draft PR) | yes | yes |
+| 2..N | yes | recomputed only if the changed-file set moved |
+| final | yes | **yes, always** |
+
+Do not decide this by memory:
+
+```bash
+keryx review blast-radius --ref "${BASE_SHA}" --previous blast-radius.json [--final]
+```
+
+It prints the decision and the reason, and reuses the previous record when
+nothing moved. The final round recomputes whatever the file set did — otherwise a
+fix introduced in round 3 gets no regression check at all, and the round that
+certifies the flow is the one that checked the least.
+
+## Fix rounds — dispositions, regressions, withdrawal
+
+### Every prior finding leaves the round with a disposition
+
+A fix round that reports only new findings is unreadable: the author cannot tell
+which of their fixes landed. Close the loop explicitly — one line per prior
+finding, in the report, before the new findings:
+
+| Disposition | Meaning |
+|---|---|
+| `closed` | Checked against the code, not against the commit message, and the defect is gone |
+| `open` | The fix does not reach the defect; say what is still true |
+| `partial` | One site of the class was fixed and the enumeration named others |
+| `regressed` | The fix removed this defect and introduced another — file the new one separately |
+| `withdrawn` | The finding was wrong. See below |
+
+**Check the code, not the commit message.** A commit titled *"report an abandoned
+sync as abandoned"* is a claim; the disposition is whether the branch it renamed
+is reachable and pinned. On a recorded round, two such commits asserted behaviour
+on lines no test could reach.
+
+### A fix is a change, and changes get reviewed
+
+The most expensive class in a multi-round review is **the defect the fix
+introduced**. It is systematically under-found, for a structural reason: the fix
+arrives framed as the answer to a finding, so it is read as an answer rather than
+as new code. It is new code.
+
+So scope A of a fix round includes the fix, reviewed on its own merits, and the
+report carries its own section:
+
+```markdown
+## Regressions the fixes introduced
+<[F-NNN] — the finding it was answering, and the new defect it created>
+```
+
+Recorded shapes, all from fixes that correctly closed the finding they answered:
+an early return added to stop a fall-through, which then skipped the work the
+caller needed; a persistence call added to save expanded state, which then
+persisted the broken state on the error path too. Both were closed correctly and
+both shipped a new bug in the same commit.
+
+### Withdrawing your own earlier finding
+
+A finding from a previous round that this round disproves is **withdrawn**,
+explicitly, at the top of the report, with the evidence — before any new finding.
+
+This is not a courtesy. An uncorrected wrong finding costs the author a fix they
+did not need, and it stays in `prior_findings` steering later rounds. Withdrawal
+is also the one self-correction this pipeline permits, and it is permitted because
+it is asymmetric: it *deletes* a claim, so it cannot inflate the finding count,
+which is the failure mode that removed the re-scoring pass from Wave C.
+
+State what made the original claim wrong, in one sentence, and if the same
+reasoning error has now happened twice in one review, say that too. A reviewer
+that names its own recurring error is calibrating; one that quietly drops a
+finding is hiding a result.
+
+## Job Context Awareness
+
+When dispatched by `job-orchestrator` or called with an explicit context path, the prompt MAY include:
+
+```
+JOB_NAME:     <job-name>
+CONTEXT_PATH: .metaproject/jobs/<job-name>/ai/context.md
+```
+
+If provided and the file exists, read the context document **before** running scope detection.
+Use it to understand:
+- Intentionally chosen libraries and patterns (do not flag as issues)
+- Architectural decisions already agreed upon, and acceptance criteria driving the Stage 1 spec compliance gate
+
+If absent, proceed normally — context is optional and non-blocking.