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.

porttyperequireddescriptionconstraint
infolioRepoPathyesThe folio’s folio graph directory.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
inoutRepoPathyesWhere to write block-qa.json.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
inrepoRepoPathThe 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.
outblock-qaRepoPathA 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:

processsteplanevia skill
Committee review of a content changeSlice the change and assign reviewersReview Coordinatorreview-heatmap

How it is deployed and reached

  • Command line. From the repository root: bun run cat block-qa:publish. cat block-qa:publish runs bun run cat-harness-tools/scripts/publish-block-qa.ts (declared in cat-harness-tools/package.json).
  • GitHub Actions. 1 workflow line(s) run its command:
workflowline
.github/workflows/folio-staging.yml484bun 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.

installnone
runtimebun
networkno
when to choose it
whenA 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.
limitsReports 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.
costOne text walk of the folio and one read per sidecar. No network.

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/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."
  }
}

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