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 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. |
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.
| port | type | required | description | constraint | |
|---|---|---|---|---|---|
| in | lock | RepoPath | yes | The 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. |
| in | caller | RepoFullName | yes | The 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 |
| in | caller-dir | RepoPath | The 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. | |
| in | sha | CommitSha | The 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). | |
| in | root | RepoPath | The 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. | |
| in | instance | InstanceId | The 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 | |
| in | base-verdict | RepoPath | A 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. | |
| in | base-root | RepoPath | A 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. | |
| in | test-path | RepoPath | What 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. | |
| in | publish | Flag | Post 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 | |
| out | record | RepoPath | 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. | 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:
| process | step | lane | via skill |
|---|---|---|---|
| Code change and review | Run the platform’s own gates | Authoring agent | platform-gates |
| Code change and review | Prepare the merge, and watch it through | Authoring agent | prepare-merge |
| The gates a change must pass before it can merge | Verdict reuse: tree already green? (NOT A GATE) | CI/CD Pipeline | platform-gates |
| The gates a change must pass before it can merge | Import hygiene (HARD) and advisories (WARN-ONLY) | CI/CD Pipeline | platform-gates |
| The gates a change must pass before it can merge | TypeScript: lint, types and tests (HARD) | CI/CD Pipeline | platform-gates |
| The gates a change must pass before it can merge | End-to-end + accessibility (HARD) | CI/CD Pipeline | platform-gates |
| The gates a change must pass before it can merge | Repository gates (HARD) | CI/CD Pipeline | platform-gates |
| The gates a change must pass before it can merge | Registered gates that never run (HARD) | CI/CD Pipeline | platform-gates |
| The gates a change must pass before it can merge | Skill-registration chain (UNMASKED) | CI/CD Pipeline | platform-gates |
| Merge the base branch in | Merge the base in, without committing | merge:main command | prepare-merge |
| Merge the base branch in | Regenerate, asking every CI gate | merge:main command | prepare-merge |
| Merge the base branch in | Resolve by hand, then regenerate | Authoring agent | prepare-merge |
| A refused merge-train member | Fix the PR, report on the PR | Owning session | prepare-merge |
| A merge train | Merge each member onto the base | Build pipeline | prepare-merge |
| A merge train | Run the gate set on the train | Build pipeline | platform-gates |
| Adopting an upstream version bump | Move the pin and open the PR | Agent | prepare-merge |
| Merge and publish a content change | Merge, on explicit confirmation | Review Committee | prepare-merge |
| Content Change and Review | Merge and publish | CI/CD Pipeline | prepare-merge |
| Guideline Updates | Merge the re-pin with its decided revisions | Re-pin steward and build pipeline | prepare-merge |
How it is deployed and reached
- Command line. From the repository root:
bun run cat judge:tree judge.cat judge:treerunsbun run cat-harness-tools/scripts/judge-tree.ts(declared incat-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.
| install | none |
| runtime | bun, python3, git |
| network | no |
When a host it reaches is refused:
| host / error | remedy |
|---|---|
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. |
| when to choose it | |
|---|---|
| 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. |
What it is made of
| role | file | |
|---|---|---|
| script | cat-harness-tools/scripts/judge-tree.ts |
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."
}
}