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.

porttyperequireddescriptionconstraint
inchangesetRepoPathyesThe 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.
inblocksRepoPathyesThe 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.
incommentsRepoPathyesThe 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.
inoutRepoPathAlso 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.
intodosRepoPathThe 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.
incommitFlagWrite 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
inbaseBranchThe base branch verdicts may NOT be committed to. Default main.string · pattern ^[A-Za-z0-9][A-Za-z0-9._/-]*$ · A git branch name
outcoverageRepoPathThe 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:

processsteplanevia skill
Committee review of a content changeIngest tagged review commentsReview Coordinatorreview-comments
Committee review of a content changeReview each sliceReview Committeereview-comments
Committee review of a content changeWithdraw a review commentReview Committeereview-comments
Data sharing agreement document life cycleReview the draft agreementReviewer (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.

installnone
runtimebun, git
networkno
when to choose it
whenThe 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.
limitsCounts 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.
costReads three JSON files and one directory; one git commit with --commit.

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

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