Folio review comments

Ingest a pull request’s tagged conversation comments (block: <label> on the first line) into review-comment/1.0.0 todos, and write them as review-comments.json. Idempotent over its previous output, whose statuses it keeps. Re-anchors every comment against the head’s blocks, following renamedFrom, and orphans a comment whose block is gone rather than dropping it.

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-coverage.

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
inrepoRepoFullNameyesowner/name of the repository the pull request is in.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
inprChangeProposalNumberyesThe edit-set’s pull request.integer · A change-proposal number — a pull request on GitHub, a merge request on GitLab
inoutRepoPathyesWhere to write review-comments.json.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
infolioRepoPathRead the head’s blocks from the folio’s manifests (as text; nothing is executed). Give this OR blocks.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
inblocks-outRepoPathWith folio: also write blocks.json, so a later run can anchor without checking the folio out.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
inblocksRepoPathA published blocks.json. The comment-triggered refresh uses this, so it never checks out the pull request’s code.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
inexistingRepoPathThe previous review-comments.json. Every comment in it is kept, with its status.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
incommitCommitShaThe head commit. Default GITHUB_SHA, else git rev-parse HEAD.string · pattern ^[0-9a-f]{7,40}$ · A git commit sha, full or abbreviated (7-40 hex digits).
intodosRepoPathThe folio’s todos graph root. Review comments committed under its todo-feedback directory, on the feature branch, win over the previously published copy.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
incommentsRepoPathRead comments from this JSON file instead of GitHub: offline runs and tests.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
outreview-commentsRepoPathA folio-review-comments/v1 file whose comments are review-comment/1.0.0 todos. Its one-line 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-comments.ts.
  • GitHub Actions. 2 workflow line(s) run its command:
workflowline
.github/workflows/folio-staging.yml630bun run "$PLATFORM_DIR/folio-assistant-core/scripts/review-comments.ts" "${TODOS_ARGS[@]}" \\
.github/workflows/folio-staging.yml1079bun run "$PLATFORM_DIR/folio-assistant-core/scripts/review-comments.ts" \\

As an API: its operation in the OpenAPI document and the MCP tool list of its layer.

installnone
runtimebun
networkyes

When a host it reaches is refused:

host / errorremedy
api.github.comnone: Reviewer comments are held by GitHub; without it the review page keeps its last ingested set.
when to choose it
whenA pull request that edits a folio has reviewer comments, and the review page, the heat map, or an editor needs them as structured todos anchored to blocks.
limitsReads conversation comments only, not line review comments (those anchor to a file line). A reviewer’s edit to a comment after it was ingested is not re-read. Statuses are moved by review-process tasks, not by this Tool; it keeps whatever existing says.
costOne paginated GitHub API call per 100 comments, plus a text walk of the manifests when folio is given.

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-comments.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-comments.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-comments",
  "title": "Folio review comments",
  "description": "Ingest a pull request's tagged conversation comments (`block: <label>` on the first line) into `review-comment/1.0.0` todos, and write them as `review-comments.json`. Idempotent over its previous output, whose statuses it keeps. Re-anchors every comment against the head's blocks, following `renamedFrom`, and orphans a comment whose block is gone rather than dropping it.",
  "install": {
    "none": true
  },
  "invoke": {
    "shell": "bun run folio-assistant-core/scripts/review-comments.ts"
  },
  "io": {
    "inputs": [
      {
        "name": "repo",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoFullName",
        "description": "`owner/name` of the repository the pull request is in.",
        "required": true,
        "arg": {
          "flag": "--repo"
        }
      },
      {
        "name": "pr",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/ChangeProposalNumber",
        "description": "The edit-set's pull request.",
        "required": true,
        "arg": {
          "flag": "--pr"
        }
      },
      {
        "name": "out",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "Where to write `review-comments.json`.",
        "required": true,
        "arg": {
          "flag": "--out"
        }
      },
      {
        "name": "folio",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "Read the head's blocks from the folio's manifests (as text; nothing is executed). Give this OR `blocks`.",
        "required": false,
        "arg": {
          "flag": "--folio"
        }
      },
      {
        "name": "blocks-out",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "With `folio`: also write `blocks.json`, so a later run can anchor without checking the folio out.",
        "required": false,
        "arg": {
          "flag": "--blocks-out"
        }
      },
      {
        "name": "blocks",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "A published `blocks.json`. The comment-triggered refresh uses this, so it never checks out the pull request's code.",
        "required": false,
        "arg": {
          "flag": "--blocks"
        }
      },
      {
        "name": "existing",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "The previous `review-comments.json`. Every comment in it is kept, with its status.",
        "required": false,
        "arg": {
          "flag": "--existing"
        }
      },
      {
        "name": "commit",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/CommitSha",
        "description": "The head commit. Default `GITHUB_SHA`, else `git rev-parse HEAD`.",
        "required": false,
        "arg": {
          "flag": "--commit"
        }
      },
      {
        "name": "todos",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "The folio's todos graph root. Review comments committed under its `todo-feedback` directory, on the feature branch, win over the previously published copy.",
        "required": false,
        "arg": {
          "flag": "--todos"
        }
      },
      {
        "name": "comments",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "Read comments from this JSON file instead of GitHub: offline runs and tests.",
        "required": false,
        "arg": {
          "flag": "--comments"
        }
      }
    ],
    "outputs": [
      {
        "name": "review-comments",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "A `folio-review-comments/v1` file whose `comments` are `review-comment/1.0.0` todos. Its one-line summary goes to stderr."
      }
    ]
  },
  "satisfies": [
    "review-comments"
  ],
  "requirements": {
    "runtime": [
      "bun"
    ],
    "network": true
  },
  "remedies": [
    {
      "host": "api.github.com",
      "none": "Reviewer comments are held by GitHub; without it the review page keeps its last ingested set."
    }
  ],
  "selection": {
    "when": "A pull request that edits a folio has reviewer comments, and the review page, the heat map, or an editor needs them as structured todos anchored to blocks.",
    "limits": "Reads conversation comments only, not line review comments (those anchor to a file line). A reviewer's edit to a comment after it was ingested is not re-read. Statuses are moved by review-process tasks, not by this Tool; it keeps whatever `existing` says.",
    "cost": "One paginated GitHub API call per 100 comments, plus a text walk of the manifests when `folio` is given."
  }
}

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