Folio block QA summary
Summarise a folio’s committed per-block QA verdicts into one block-qa.json a staging preview publishes: each block is failing (a FRESH verdict failed, with the worst severity), stale (a verdict predates the block’s current files), passing, or unaudited. Freshness is the QA sweep’s own rule, including the uses-graph hash for graph-scoped criteria. Runs no checker and writes no verdict.
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-heatmap
The review page’s heat map: a section-by-metric table that tells a reviewer of a large document where to look first. Says what each column MEANS and what it must NOT be read as, where each number comes from, what a column says when a build lacks its data, and how the colour was chosen. Use when a reviewer or author asks “where do I start”, reads a number off the heat map, or asks why coverage or QA say “no data”; and before adding a column.
Source: cat-harness/skills/authoring/authoring-core/review-heatmap.md.
The skill declares no I/O contract (schemas/skills/review-heatmap/{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 | folio | RepoPath | yes | The folio’s folio graph directory. | string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments. |
| in | out | RepoPath | yes | Where to write block-qa.json. | string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments. |
| in | repo | RepoPath | The folio’s instance root, where verdicts are anchored. Default: found from folio exactly as the QA sweep finds it. | string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments. | |
| out | block-qa | RepoPath | A folio-block-qa-summary/v1 file keyed by block label. Its counts go 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 | Slice the change and assign reviewers | Review Coordinator | review-heatmap |
How it is deployed and reached
- Command line. From the repository root:
bun run cat block-qa:publish.cat block-qa:publishrunsbun run cat-harness-tools/scripts/publish-block-qa.ts(declared incat-harness-tools/package.json). - GitHub Actions. 1 workflow line(s) run its command:
| workflow | line | |
|---|---|---|
.github/workflows/folio-staging.yml | 484 | bun run "$PLATFORM_DIR/cat-harness-tools/scripts/publish-block-qa.ts" \\ |
As an API: its operation in the OpenAPI document and the MCP tool list of its layer.
| install | none |
| runtime | bun |
| network | no |
| when to choose it | |
|---|---|
| when | A staging preview is being built and its review page’s heat map should show QA per section, from what the folio’s QA sweep last recorded. |
| limits | Reports the LAST sweep: in a staging build, the sweep the job ran just before it; otherwise the committed verdicts. A folio never swept reads unaudited throughout. Verdicts are read at the instance root, so a folio in a subfolder is read at its own root, then in the folio directory. |
| cost | One text walk of the folio and one read per sidecar. No network. |
What it is made of
| role | file | |
|---|---|---|
| definition | folio-assistant-core/tools/folio-block-qa-summary/folio-block-qa-summary.ts | |
| script | cat-harness-tools/scripts/publish-block-qa.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-block-qa-summary.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-block-qa-summary.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-block-qa-summary",
"title": "Folio block QA summary",
"description": "Summarise a folio's committed per-block QA verdicts into one `block-qa.json` a staging preview publishes: each block is failing (a FRESH verdict failed, with the worst severity), stale (a verdict predates the block's current files), passing, or unaudited. Freshness is the QA sweep's own rule, including the uses-graph hash for graph-scoped criteria. Runs no checker and writes no verdict.",
"install": {
"none": true
},
"invoke": {
"shell": "bun run cat block-qa:publish"
},
"io": {
"inputs": [
{
"name": "folio",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
"description": "The folio's `folio` graph directory.",
"required": true,
"arg": {
"flag": "--folio"
}
},
{
"name": "out",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
"description": "Where to write `block-qa.json`.",
"required": true,
"arg": {
"flag": "--out"
}
},
{
"name": "repo",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
"description": "The folio's instance root, where verdicts are anchored. Default: found from `folio` exactly as the QA sweep finds it.",
"required": false,
"arg": {
"flag": "--repo"
}
}
],
"outputs": [
{
"name": "block-qa",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
"description": "A `folio-block-qa-summary/v1` file keyed by block label. Its counts go to stderr."
}
]
},
"satisfies": [
"review-heatmap"
],
"requirements": {
"runtime": [
"bun"
],
"network": false
},
"selection": {
"when": "A staging preview is being built and its review page's heat map should show QA per section, from what the folio's QA sweep last recorded.",
"limits": "Reports the LAST sweep: in a staging build, the sweep the job ran just before it; otherwise the committed verdicts. A folio never swept reads unaudited throughout. Verdicts are read at the instance root, so a folio in a subfolder is read at its own root, then in the folio directory.",
"cost": "One text walk of the folio and one read per sidecar. No network."
}
}