Judge a tree and record the verdict by digest

Run the layer PR-check gates and tests on a composed tree (head) and on its base, or reuse a stored verdict whose digest is the base tree’s, compare them with the layer-pr-checks compare scripts, and write a verdict record: {treeDigest, runner {kind agentgithub-actionslocal, id}, startedAt, finishedAt, gates [{name, exit, seconds, skipped?}], tests {total, failed, new}, verdict greenredunknown}. With a token it publishes the verdict as the commit status judge-tree; check answers whether any runner judged a digest green; sample re-runs a seeded few gates of a record.

Skills it satisfies

A skill states the capability; this Tool is one way to exercise it. Each skill’s declared input and output contract follows, where it has one.

platform-gates

bun test passing is not the gates passing. What to run before you push, why the list is derived from the CI workflow rather than written down, and what a *:check failure is actually telling you to do.

Source: cat-harness/skills/process/process-core/platform-gates.md.

Also satisfied by: gates, ci-code-quality-gates.

The skill declares no I/O contract (schemas/skills/platform-gates/{input,output}.schema.json).

prepare-merge

Take a feature branch to a clean, conflict-free, green, pushed state so it can be merged with no surprises: base merged in, generated files regenerated, the folio’s content-type gates run, then pushed. It does NOT merge and does NOT push to the default branch. Use for “prepare-merge”, “make it mergeable”, “ship it”.

Source: cat-harness/sdlc/skills/sdlc-core/prepare-merge.md.

Also satisfied by: ci-merge-main, gates-merged, merge-train.

The skill declares no I/O contract (schemas/skills/prepare-merge/{input,output}.schema.json).

Inputs and outputs

Each port names a shared type by IRI, so two Tools for one skill can be checked for interchangeability.

porttyperequireddescriptionconstraint
inlockRepoPathyesThe index.lock.json whose fixity digests name every layer but the caller.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
incallerRepoFullNameyesThe caller as owner/name (or its lock layer): the entry replaced by its PR tree. Every runner must name it the same way.string · pattern ^[A-Za-z0-9][A-Za-z0-9._-]*\\/[A-Za-z0-9][A-Za-z0-9._-]*$ · A forge repository’s full name, owner/name
incaller-dirRepoPathThe caller’s git checkout; its HEAD^{tree} (or –sha’s) is the PR tree.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
inshaCommitShaThe head commit: whose tree is read from –caller-dir, and where the status is published.string · pattern ^[0-9a-f]{7,40}$ · A git commit sha, full or abbreviated (7-40 hex digits).
inrootRepoPathThe mounted index with the caller swapped in, where run-gates.py runs.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
ininstanceInstanceIdThe own layer(s) run-gates.py judges; repeatable.string · pattern ^[A-Za-z0-9][A-Za-z0-9._-]*$ · A workflow instance id — the stem of a file in the bean graph’s workflow-state node
inbase-verdictRepoPathA stored verdict record standing in for the base run; refused unless its treeDigest is the base tree’s (–base-tree).string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
inbase-rootRepoPathA mounted base tree to run the gates on instead.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
intest-pathRepoPathWhat bun test runs on each side; none means no tests.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
inpublishFlagPost the commit status judge-tree when GITHUB_TOKEN/GH_TOKEN is set; without one, the record file is the verdict.boolean · A boolean switch — projects to a bare flag, with no value word
outrecordRepoPathThe verdict record, <records-dir>/<treeDigest>.json unless –out names it; valid against the tools layer’s schemas/verdict-record.schema.json. Three exit codes: 0 green, 1 red, 2 COULD NOT DETERMINE (no judging scripts, a stored base verdict for another tree, a compare script that crashed, or no gate ran). 2 is never green, and neither is a verdict for another digest.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.

Processes and tasks

Steps this Tool can carry out, because each names a skill it satisfies:

processsteplanevia skill
Code change and reviewRun the platform’s own gatesAuthoring agentplatform-gates
Code change and reviewPrepare the merge, and watch it throughAuthoring agentprepare-merge
The gates a change must pass before it can mergeVerdict reuse: tree already green? (NOT A GATE)CI/CD Pipelineplatform-gates
The gates a change must pass before it can mergeImport hygiene (HARD) and advisories (WARN-ONLY)CI/CD Pipelineplatform-gates
The gates a change must pass before it can mergeTypeScript: lint, types and tests (HARD)CI/CD Pipelineplatform-gates
The gates a change must pass before it can mergeEnd-to-end + accessibility (HARD)CI/CD Pipelineplatform-gates
The gates a change must pass before it can mergeRepository gates (HARD)CI/CD Pipelineplatform-gates
The gates a change must pass before it can mergeRegistered gates that never run (HARD)CI/CD Pipelineplatform-gates
The gates a change must pass before it can mergeSkill-registration chain (UNMASKED)CI/CD Pipelineplatform-gates
Merge the base branch inMerge the base in, without committingmerge:main commandprepare-merge
Merge the base branch inRegenerate, asking every CI gatemerge:main commandprepare-merge
Merge the base branch inResolve by hand, then regenerateAuthoring agentprepare-merge
A refused merge-train memberFix the PR, report on the PROwning sessionprepare-merge
A merge trainMerge each member onto the baseBuild pipelineprepare-merge
A merge trainRun the gate set on the trainBuild pipelineplatform-gates
Adopting an upstream version bumpMove the pin and open the PRAgentprepare-merge
Merge and publish a content changeMerge, on explicit confirmationReview Committeeprepare-merge
Content Change and ReviewMerge and publishCI/CD Pipelineprepare-merge
Guideline UpdatesMerge the re-pin with its decided revisionsRe-pin steward and build pipelineprepare-merge

How it is deployed and reached

  • Command line. From the repository root: bun run cat judge:tree judge. cat judge:tree runs bun run cat-harness-tools/scripts/judge-tree.ts (declared in cat-harness-tools/package.json).
  • GitHub Actions. No workflow in this checkout runs its command.

As an API: its operation in the OpenAPI document and the MCP tool list of its layer.

installnone
runtimebun, python3, git
networkno

When a host it reaches is refused:

host / errorremedy
api.github.comnone: Publishing and check against statuses need the API; without it the record file is the verdict and check --records-dir reads records instead.
when to choose it
whenWhen a PR’s tree must be judged and any runner can do it: an agent before pushing, a developer locally, or CI. Then verdict-check.yml passes the PR on the published verdict instead of re-running ~300 gates per side.
limitsThe digest trusts the lock’s fixity digests for every layer but the caller, so a run that takes lower layers at main instead of the lock judges a tree the digest does not name. A verdict answers only for its exact digest: a change to the judging scripts is a new digest and needs a new verdict.
costThat of layer-pr-checks for one side, or two when no stored base verdict exists: gates dominate (minutes to tens of minutes). digest and check are one hash and at most one HTTP request.

What it is made of

Linked data

The Tool is published as its own JSON-LD document at its IRI, https://litlfred.github.io/folio-assistant/cat-harness/tools/judge-tree.jsonld, partOf its layer’s document. The node below is the definition this page was drawn from, and is embedded in the page as application/ld+json.

{
  "@context": "https://litlfred.github.io/folio-assistant/cat-harness/cat-harness.context.jsonld",
  "@id": "https://litlfred.github.io/folio-assistant/cat-harness/tools/judge-tree.jsonld",
  "@type": "https://litlfred.github.io/cat-harness/v0/ns/Tool",
  "partOf": "https://litlfred.github.io/folio-assistant/cat-harness/cat-harness.jsonld",
  "name": "judge-tree",
  "title": "Judge a tree and record the verdict by digest",
  "description": "Run the layer PR-check gates and tests on a composed tree (head) and on its base, or reuse a stored verdict whose digest is the base tree's, compare them with the layer-pr-checks compare scripts, and write a verdict record: {treeDigest, runner {kind agent|github-actions|local, id}, startedAt, finishedAt, gates [{name, exit, seconds, skipped?}], tests {total, failed, new}, verdict green|red|unknown}. With a token it publishes the verdict as the commit status `judge-tree`; `check` answers whether any runner judged a digest green; `sample` re-runs a seeded few gates of a record.",
  "install": {
    "none": true
  },
  "invoke": {
    "shell": "bun run cat judge:tree judge"
  },
  "io": {
    "inputs": [
      {
        "name": "lock",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "The index.lock.json whose fixity digests name every layer but the caller.",
        "required": true,
        "arg": {
          "flag": "--lock"
        }
      },
      {
        "name": "caller",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoFullName",
        "description": "The caller as owner/name (or its lock layer): the entry replaced by its PR tree. Every runner must name it the same way.",
        "required": true,
        "arg": {
          "flag": "--caller"
        }
      },
      {
        "name": "caller-dir",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "The caller's git checkout; its HEAD^{tree} (or --sha's) is the PR tree.",
        "required": false,
        "arg": {
          "flag": "--caller-dir"
        }
      },
      {
        "name": "sha",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/CommitSha",
        "description": "The head commit: whose tree is read from --caller-dir, and where the status is published.",
        "required": false,
        "arg": {
          "flag": "--sha"
        }
      },
      {
        "name": "root",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "The mounted index with the caller swapped in, where run-gates.py runs.",
        "required": false,
        "arg": {
          "flag": "--root"
        }
      },
      {
        "name": "instance",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/InstanceId",
        "description": "The own layer(s) run-gates.py judges; repeatable.",
        "required": false,
        "arg": {
          "flag": "--instance"
        }
      },
      {
        "name": "base-verdict",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "A stored verdict record standing in for the base run; refused unless its treeDigest is the base tree's (--base-tree).",
        "required": false,
        "arg": {
          "flag": "--base-verdict"
        }
      },
      {
        "name": "base-root",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "A mounted base tree to run the gates on instead.",
        "required": false,
        "arg": {
          "flag": "--base-root"
        }
      },
      {
        "name": "test-path",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "What `bun test` runs on each side; none means no tests.",
        "required": false,
        "arg": {
          "flag": "--test-path"
        }
      },
      {
        "name": "publish",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Flag",
        "description": "Post the commit status `judge-tree` when GITHUB_TOKEN/GH_TOKEN is set; without one, the record file is the verdict.",
        "required": false,
        "arg": {
          "flag": "--publish"
        }
      }
    ],
    "outputs": [
      {
        "name": "record",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "The verdict record, `<records-dir>/<treeDigest>.json` unless --out names it; valid against the tools layer's `schemas/verdict-record.schema.json`. Three exit codes: 0 green, 1 red, 2 COULD NOT DETERMINE (no judging scripts, a stored base verdict for another tree, a compare script that crashed, or no gate ran). 2 is never green, and neither is a verdict for another digest."
      }
    ]
  },
  "satisfies": [
    "platform-gates",
    "prepare-merge"
  ],
  "requirements": {
    "runtime": [
      "bun",
      "python3",
      "git"
    ],
    "network": false
  },
  "remedies": [
    {
      "host": "api.github.com",
      "none": "Publishing and `check` against statuses need the API; without it the record file is the verdict and `check --records-dir` reads records instead."
    }
  ],
  "selection": {
    "when": "When a PR's tree must be judged and any runner can do it: an agent before pushing, a developer locally, or CI. Then `verdict-check.yml` passes the PR on the published verdict instead of re-running ~300 gates per side.",
    "limits": "The digest trusts the lock's fixity digests for every layer but the caller, so a run that takes lower layers at main instead of the lock judges a tree the digest does not name. A verdict answers only for its exact digest: a change to the judging scripts is a new digest and needs a new verdict.",
    "cost": "That of layer-pr-checks for one side, or two when no stored base verdict exists: gates dominate (minutes to tens of minutes). `digest` and `check` are one hash and at most one HTTP request."
  }
}

folio-assistant — code under the Apache License 2.0, documentation under CC BY 3.0. Generated schema and API references are rebuilt from source on every push to main.

deployed dev