PR review swarm

1nika: pr-review-fanout2​3model: ollama/qwen3.5:4b   # local tool-calling model · swap for anthropic/claude-sonnet-4-6 for depth4​5const:6  base_ref: "main"7  review_root: "src/"      # the swarm's territory · keep in step with permits.fs.read8​9⛨permits:10  # The argv form (`exec.command:`) runs one named program with its arguments11  # and no shell between them, which is what makes a program allowlist mean12  # something. A `exec.shell:` task is refused against a list — measured:13  # `NIKA-SEC-004 · a shell-string command cannot be verified against a14  # permits.exec program allowlist (a pipeline can launch any program) — use15  # the array form`. Only `exec: true` admits a shell, and this workflow16  # deliberately never needs one.17  #18  # An allowlisted program is not an unconfined one: `git` runs inside the19  # `fs:` boundary below, which is why the header's second `Needs ·` line is20  # about git's global config rather than about git.21  ⛨exec: ["git"]22  ⛨tools: ["nika:done", "nika:grep", "nika:jq", "nika:prompt", "nika:read", "nika:write"]23  ⛨fs:24    # `./src/**` covers the directory AND every descendant at any depth, which25    # is what both consumers need: `nika:grep` opens `./src` itself, and the26    # swarm reads files nested under it. A bare `./src` would cover only the27    # directory entry and refuse every file inside it.28    #29    # This bound is why `files` below filters the diff down to `const.review_root`:30    # `git diff` happily reports `Cargo.toml` or `.github/workflows/ci.yml`, and31    # an agent handed one of those would die `NIKA-SEC-004` mid-swarm. The claim32    # and the territory are kept equal on purpose.33    ⛨read: ["./src/**"]34    ⛨write: ["./REVIEW.md"]35​36tasks:37  # The human gate (NEP-0002 · v2.2). `git diff` output is UNTRUSTED38  # content — a hostile branch names its own files — and this workflow39  # pairs it with a private `fs.read` and egress-capable tasks: the40  # lethal trifecta, unless a human dominates the path. The gate comes41  # FIRST so every task the diff output reaches descends from it (a gate42  # on a sibling branch dominates nothing — the data edge would bypass43  # it), and each root CONSUMES the answer affirmatively (NEP-0020 — a44  # bare `after:` admits the refusal: it settles success with value45  # false). Under `--answer approve=true` the CI one-pass answers it here.46  # The one [headless-prompt] hint is the price of a real gate — pay it here.47  approve:48    ◆invoke:49      tool: "nika:prompt"50      args:51        mode: "confirm"52        message: "diff ${{ const.base_ref }}...HEAD and fan out one review agent per changed file?"53​54  # `--diff-filter=d` drops deletions: a file that no longer exists cannot be55  # reviewed, and asking an agent to read it just burns a turn on an error.56  changed:57    after: { approve: success }58    with:59      go: ${{ tasks.approve.output }}60    when: ${{ with.go == true }}     # « no » at the gate → no diff, no swarm61    ▷exec:62      command: ["git", "diff", "--name-only", "--diff-filter=d", "${{ const.base_ref }}...HEAD"]63​64  files:65    with:66      changed: ${{ tasks.changed.output }}67    when: ${{ with.changed != null && size(with.changed) > 0 }}  # a refused gate skips the diff (null) · an empty diff has nothing to split68    ◆invoke:69      tool: "nika:jq"70      args:71        input: "${{ with.changed }}"72        expression: >-73          split("\n")74          | map(select(length > 0))75          | map(select(startswith("${{ const.review_root }}")))76​77  # The deterministic pass. Debt does not need a model to be found, and this78  # runs whether or not anything changed. It too descends from the gate —79  # dominance is structural: a sibling branch that bypasses `approve`80  # would re-open the trifecta no matter how clean its own content is.81  todo_sweep:82    after: { approve: success }83    with:84      go: ${{ tasks.approve.output }}85    when: ${{ with.go == true }}     # the same « no » closes this branch too86    ◆invoke:87      tool: "nika:grep"88      args:89        pattern: "TODO|FIXME|HACK"90        path: "./src"91​92  reviews:93    with:94      files: ${{ tasks.files.output }}95    for_each:96      items: ${{ with.files }}97      max_parallel: 4                    # four reviewers in flight · not forty98      fail_fast: false                   # one reviewer's bad day is not the swarm's99    on_error:100      recover: null                    # a budget-exhausted review yields null · filtered below101    ✦agent:102      system: >-103        You are a precise code reviewer. Read the file, then finish with ONLY104        the schema'd object ({file, findings: [{severity, message, line}]} ·105        severity exactly one of blocker|high|med|low), then call nika:done.106      prompt: "Review ${{ item }} · bugs first, then risky patterns. Read it before judging."107      tools:108        - "nika:read"                  # read-only swarm · least privilege109        - "nika:done"110      max_turns: 6                     # read · think · answer · a little slack111      max_tokens_total: 30000          # per reviewer · the swarm's ceiling is this × the file count112      # `additionalProperties: false` on BOTH object nodes. Without it on the113      # inner one, a provider may add keys to a finding and the sort below is114      # ordering a shape that changed between runs.115      schema:116        type: object117        additionalProperties: false118        required: [file, findings]119        properties:120          file: { type: string }121          findings:122            type: array123            items:124              type: object125              additionalProperties: false126              required: [severity, message]127              properties:128                severity: { type: string, enum: [blocker, high, med, low] }129                message: { type: string }130                line: { type: integer }131​132  # The fan-in.133  #   `. // []`      · a clean diff SKIPS the swarm (an empty for_each resolves134  #                    null), and the fan-in has to survive its own good news.135  #   `select(. != null)` · the reviewers that recovered leave here, by value.136  #   `.findings[] + {file}` · flatten [[finding]] → [finding], each carrying137  #                    the file it came from.138  #   the rank object · `sort_by(.severity)` would be ALPHABETICAL, which puts139  #                    `low` above `med`. Severity order is a decision, so it is140  #                    written down.141  merged:142    with:143      reviews: ${{ tasks.reviews.output }}144    ◆invoke:145      tool: "nika:jq"146      args:147        input: "${{ with.reviews }}"148        expression: >-149          (. // [])150          | map(select(. != null))151          | map(.findings[] + { file: .file })152          | sort_by({ blocker: 0, high: 1, med: 2, low: 3 }[.severity])153​154  summary:155    with:156      merged: ${{ tasks.merged.output }}157      todo_sweep: ${{ tasks.todo_sweep.output }}158    when: ${{ with.todo_sweep != null && size(with.todo_sweep) > 0 }}  # skipped (null) or an empty sweep · no page to write159    ◇infer:160      max_tokens: 2500                 # a review page · not the whole diff back161      prompt: |162        Merge these review findings into REVIEW.md · blockers first ·163        ${{ with.merged }}164        Open TODO debt found by grep ·165        ${{ with.todo_sweep }}166        End with a verdict · ship / fix-first / redesign.167​168  save:169    with:170      summary: ${{ tasks.summary.output }}171    when: ${{ with.summary != null && size(with.summary) > 0 }}   # skipped (null) or an EMPTY answer · never a 0-byte REVIEW.md172    ◆invoke:173      tool: "nika:write"174      args:175        path: "./REVIEW.md"176        content: "${{ with.summary }}"177​178outputs:179  findings:180    value: ${{ tasks.merged.output }}181    description: "Every finding, blockers first, each attributed to its file"182  review:183    value: ${{ tasks.summary.output }}184    description: "The page a human reads · also written to ./REVIEW.md"185​