Folio review coverage
Compute the two facts content-change-review.bpmn’s coverage gate (GW_Covered) reads: uncoveredBlocks, the changed blocks with no reviewer verdict on their CURRENT hash, and openDefects. Reads a preview’s changeset.json, blocks.json and review-comments.json. With --commit, writes the ingested folio-review-verdict/v1 verdicts into the todos graph’s declared review-verdicts directory and commits them to the edit-set’s FEATURE branch; refused on the base branch and a detached HEAD. Prints the facts as JSON on stdout.
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.
review-comments
Reviewer comments on a folio’s edit-set, from a tagged pull-request comment to a structured todo on the review page. Covers the tag a reviewer types, how the comments are ingested into review-comment/1.0.0 todos, where the published review-comments.json comes from and when it refreshes, how a comment follows a renamed block and survives a removed one, who may change a comment’s status, and how to change this process. Use when a reviewer asks how to comment on a block, when the review page shows no comments or a wrong one, when editing the ingestion, or when a folio’s staging workflow is set up.
Source: folio-assistant-core/skills/content/content-lifecycle-ext/review-comments.md.
Also satisfied by: folio-review-comment-move, folio-review-comments.
The skill declares no I/O contract (schemas/skills/review-comments/{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 | changeset | RepoPath | yes | The preview’s changeset.json: which blocks changed. | string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments. |
| in | blocks | RepoPath | yes | The preview’s blocks.json: each head block’s current hash. | string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments. |
| in | comments | RepoPath | yes | The preview’s review-comments.json: open defects, and the ingested verdicts. | string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments. |
| in | out | RepoPath | Also write the full folio-review-coverage/v1 report, with the uncovered labels and the stale verdicts. | string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments. | |
| in | todos | RepoPath | The folio’s todos graph root. Verdicts committed under its review-verdicts directory win over the published copy. | string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments. | |
| in | commit | Flag | Write the published verdicts into the declared directory and commit them to the current feature branch. Needs todos. | boolean · A boolean switch — projects to a bare flag, with no value word | |
| in | base | Branch | The base branch verdicts may NOT be committed to. Default main. | string · pattern ^[A-Za-z0-9][A-Za-z0-9._/-]*$ · A git branch name | |
| out | coverage | RepoPath | The folio-review-coverage/v1 report at out. Its facts field, {"uncoveredBlocks": n, "openDefects": n}, is also printed alone on stdout: what workflow_complete takes for GW_Covered. The summary goes to stderr. | 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 |
|---|---|---|---|
| Committee review of a content change | Ingest tagged review comments | Review Coordinator | review-comments |
| Committee review of a content change | Review each slice | Review Committee | review-comments |
| Committee review of a content change | Withdraw a review comment | Review Committee | review-comments |
| Data sharing agreement document life cycle | Review the draft agreement | Reviewer (legal, policy) | review-comments |
How it is deployed and reached
- Command line. From the repository root:
bun run folio-assistant-core/scripts/review-coverage.ts. - 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, git |
| network | no |
| when to choose it | |
|---|---|
| when | The review coordinator reaches GW_Covered and needs to know, rather than guess, whether every changed block has been read at its current version and no defect is still open. |
| limits | Counts only what reviewers recorded as verdicts. A block nobody tagged is uncovered even if somebody read it. A verdict on an older hash is reported as stale and not counted. |
| cost | Reads three JSON files and one directory; one git commit with --commit. |
What it is made of
| role | file | |
|---|---|---|
| definition | folio-assistant-core/tools/folio-review-coverage/folio-review-coverage.ts | |
| script | folio-assistant-core/scripts/review-coverage.ts |
Linked data
The Tool is published as its own JSON-LD document at its IRI, https://litlfred.github.io/folio-assistant/folio-assistant-core/tools/folio-review-coverage.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/folio-assistant-core/folio-assistant-core.context.jsonld",
"@id": "https://litlfred.github.io/folio-assistant/folio-assistant-core/tools/folio-review-coverage.jsonld",
"@type": "https://litlfred.github.io/cat-harness/v0/ns/Tool",
"partOf": "https://litlfred.github.io/folio-assistant/folio-assistant-core/folio-assistant-core.jsonld",
"name": "folio-review-coverage",
"title": "Folio review coverage",
"description": "Compute the two facts `content-change-review.bpmn`'s coverage gate (`GW_Covered`) reads: `uncoveredBlocks`, the changed blocks with no reviewer verdict on their CURRENT hash, and `openDefects`. Reads a preview's `changeset.json`, `blocks.json` and `review-comments.json`. With `--commit`, writes the ingested `folio-review-verdict/v1` verdicts into the todos graph's declared `review-verdicts` directory and commits them to the edit-set's FEATURE branch; refused on the base branch and a detached HEAD. Prints the facts as JSON on stdout.",
"install": {
"none": true
},
"invoke": {
"shell": "bun run folio-assistant-core/scripts/review-coverage.ts"
},
"io": {
"inputs": [
{
"name": "changeset",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
"description": "The preview's `changeset.json`: which blocks changed.",
"required": true,
"arg": {
"flag": "--changeset"
}
},
{
"name": "blocks",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
"description": "The preview's `blocks.json`: each head block's current hash.",
"required": true,
"arg": {
"flag": "--blocks"
}
},
{
"name": "comments",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
"description": "The preview's `review-comments.json`: open defects, and the ingested verdicts.",
"required": true,
"arg": {
"flag": "--comments"
}
},
{
"name": "out",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
"description": "Also write the full `folio-review-coverage/v1` report, with the uncovered labels and the stale verdicts.",
"required": false,
"arg": {
"flag": "--out"
}
},
{
"name": "todos",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
"description": "The folio's todos graph root. Verdicts committed under its `review-verdicts` directory win over the published copy.",
"required": false,
"arg": {
"flag": "--todos"
}
},
{
"name": "commit",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Flag",
"description": "Write the published verdicts into the declared directory and commit them to the current feature branch. Needs `todos`.",
"required": false,
"arg": {
"flag": "--commit"
}
},
{
"name": "base",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Branch",
"description": "The base branch verdicts may NOT be committed to. Default `main`.",
"required": false,
"arg": {
"flag": "--base"
}
}
],
"outputs": [
{
"name": "coverage",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
"description": "The `folio-review-coverage/v1` report at `out`. Its `facts` field, `{\"uncoveredBlocks\": n, \"openDefects\": n}`, is also printed alone on stdout: what `workflow_complete` takes for `GW_Covered`. The summary goes to stderr."
}
]
},
"satisfies": [
"review-comments"
],
"requirements": {
"runtime": [
"bun",
"git"
],
"network": false
},
"selection": {
"when": "The review coordinator reaches `GW_Covered` and needs to know, rather than guess, whether every changed block has been read at its current version and no defect is still open.",
"limits": "Counts only what reviewers recorded as verdicts. A block nobody tagged is uncovered even if somebody read it. A verdict on an older hash is reported as stale and not counted.",
"cost": "Reads three JSON files and one directory; one git commit with `--commit`."
}
}