Check a review log and its repository’s issues for changes

The mechanical check a review-log watcher runs on every poll. Given a drafting sheet’s Contributor Feedback values and the folio repository, it reads the repository’s open and closed issues (leaving out pull requests, issues labelled no-sheet and, with --author, issues someone else opened) and compares a digest of them and of the cells people set (Title, Selected Sections, Contributor Feedback, Disposition, Ready for agent, Ready for merge, Dispositions confirmed; on a public-comment log also Committee Feedback, TWG (CS), TWG (human) and Change Set (human)) with the last check’s. Unchanged: it prints {"status":"unchanged"} and exits 0. Changed: it exits 10 and lists what changed (issue opened, updated or closed; a cell’s old and new text), the Contributor Feedback rows to append, one per issue that no row’s Issue cell links yet (Title the issue’s title, the first Contributor Feedback column @login (#N): first paragraph, Issue the issue’s URL; a closed issue’s row marked closed), and closedRows, the rows linking a closed issue, which the watcher hides with their text struck through. A read with no Issue column (a public-comment log’s Review Change Sets) tracks only issues labelled change-set unless --label says otherwise, and appends no rows: each open issue is reported as an issue-unlinked change instead. It writes no sheet and no issue: the watcher appends the rows and does the agent pass. With --accept it stores the new state for the next poll to compare against.

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-log-watch

Poll a review log (a drafting Contributor Feedback sheet, or a public-comment sheet’s Review Change Sets) and its folio repository’s issues mechanically, with Tool review-log-watch, and start agent work only when a cell people set or an open issue changed. Each issue that no row links yet becomes a Contributor Feedback row, and a closed issue’s row is hidden with its text struck through. Use on every wake of a review-log watcher, and when setting up a watcher for a new log.

Source: folio-assistant-core/skills/content/folio-document-adapter/review-log-watch.md.

The skill declares no I/O contract (schemas/skills/review-log-watch/{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
inrepoRepoPathyesThe folio repository, owner/name, whose issues, open and closed, are read with gh api.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
insheetRepoPathyesThe Contributor Feedback tab’s values (a public-comment log: Review Change Sets) as JSON: the Sheets API values array (or the whole get_values answer), from row 1, so the header row (first cell Change-set) is found.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
instateRepoPathyesThe last check’s state file. Missing on the first check, which reports every open issue as opened.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
inissuesRepoPathIssues as JSON (the issues API’s shape), instead of reading them with gh api. For tests and offline runs.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
inauthorRepoPathOnly issues this GitHub login opened. Default every author.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
insheetHashRepoPathThe sheet script’s hash of the person-set cells, Watch!G1. Given, it stands for the cells, so --sheet needs only the header row and the Issue column.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
inlabelRepoPathOnly issues with this label, e.g. change-set. Default every issue on a read with an Issue column, and change-set on one without (a public-comment log).string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
inskipLabelRepoPathThe label that keeps an issue off the sheet. Default no-sheet.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
outresultRepoPathJSON on standard output: status (unchanged or changed), digest, and when changed changes, append (rows aligned to the header, each with closed), closedRows and state. Exit 0 unchanged, 10 changed, 2 usage.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
Record agent stepRead back Agentic status and Staging reviewAuthoring agentreview-log-watch
Review-log watchRead the Contributor Feedback tabLog watcher (authoring agent)review-log-watch
Review-log watchRun the review-log-watch checkLog watcher (authoring agent)review-log-watch
Review-log watchHand new feedback to the row’s agent; take over stalled rowsLog watcher (authoring agent)review-log-watch
Review-log watchAppend rows for new issues; hide closed onesLog watcher (authoring agent)review-log-watch
Review-log watchAccept the new stateLog watcher (authoring agent)review-log-watch

How it is deployed and reached

  • Command line. From the repository root: bun run folio-assistant-core/tools/review-log-watch/watch.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
networkyes

When a host it reaches is refused:

host / errorremedy
api.github.comnone: The issues are held by GitHub. Without it, pass --issues with a saved copy of the issues API answer; the check then compares the sheet against that copy.
when to choose it
whenOn every poll of a review-log watcher, before any agent work: the agent pass runs only when this reports changed.
limitsReads one tab and one repository’s issues; it never writes the sheet or GitHub. It sees an edit only in the watched headers, so the agent’s own Green columns and the script’s Grey ones never wake the watcher.
costOne gh api call per 100 issues and one small JSON file; well under a second.

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/review-log-watch.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/review-log-watch.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": "review-log-watch",
  "title": "Check a review log and its repository's issues for changes",
  "description": "The mechanical check a review-log watcher runs on every poll. Given a drafting sheet's Contributor Feedback values and the folio repository, it reads the repository's open and closed issues (leaving out pull requests, issues labelled `no-sheet` and, with `--author`, issues someone else opened) and compares a digest of them and of the cells people set (Title, Selected Sections, Contributor Feedback, Disposition, Ready for agent, Ready for merge, Dispositions confirmed; on a public-comment log also Committee Feedback, TWG (CS), TWG (human) and Change Set (human)) with the last check's. Unchanged: it prints `{\"status\":\"unchanged\"}` and exits 0. Changed: it exits 10 and lists what changed (issue opened, updated or closed; a cell's old and new text), the Contributor Feedback rows to append, one per issue that no row's Issue cell links yet (Title the issue's title, the first Contributor Feedback column `@login (#N): first paragraph`, Issue the issue's URL; a closed issue's row marked `closed`), and `closedRows`, the rows linking a closed issue, which the watcher hides with their text struck through. A read with no Issue column (a public-comment log's Review Change Sets) tracks only issues labelled `change-set` unless `--label` says otherwise, and appends no rows: each open issue is reported as an `issue-unlinked` change instead. It writes no sheet and no issue: the watcher appends the rows and does the agent pass. With `--accept` it stores the new state for the next poll to compare against.",
  "install": {
    "none": true
  },
  "invoke": {
    "shell": "bun run folio-assistant-core/tools/review-log-watch/watch.ts"
  },
  "io": {
    "inputs": [
      {
        "name": "repo",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "The folio repository, `owner/name`, whose issues, open and closed, are read with `gh api`.",
        "required": true,
        "arg": {
          "flag": "--repo"
        }
      },
      {
        "name": "sheet",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "The Contributor Feedback tab's values (a public-comment log: Review Change Sets) as JSON: the Sheets API `values` array (or the whole `get_values` answer), from row 1, so the header row (first cell `Change-set`) is found.",
        "required": true,
        "arg": {
          "flag": "--sheet"
        }
      },
      {
        "name": "state",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "The last check's state file. Missing on the first check, which reports every open issue as opened.",
        "required": true,
        "arg": {
          "flag": "--state"
        }
      },
      {
        "name": "issues",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "Issues as JSON (the issues API's shape), instead of reading them with `gh api`. For tests and offline runs.",
        "required": false,
        "arg": {
          "flag": "--issues"
        }
      },
      {
        "name": "author",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "Only issues this GitHub login opened. Default every author.",
        "required": false,
        "arg": {
          "flag": "--author"
        }
      },
      {
        "name": "sheetHash",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "The sheet script's hash of the person-set cells, Watch!G1. Given, it stands for the cells, so `--sheet` needs only the header row and the Issue column.",
        "required": false,
        "arg": {
          "flag": "--sheet-hash"
        }
      },
      {
        "name": "label",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "Only issues with this label, e.g. `change-set`. Default every issue on a read with an Issue column, and `change-set` on one without (a public-comment log).",
        "required": false,
        "arg": {
          "flag": "--label"
        }
      },
      {
        "name": "skipLabel",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "The label that keeps an issue off the sheet. Default `no-sheet`.",
        "required": false,
        "arg": {
          "flag": "--skip-label"
        }
      }
    ],
    "outputs": [
      {
        "name": "result",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "JSON on standard output: `status` (`unchanged` or `changed`), `digest`, and when changed `changes`, `append` (rows aligned to the header, each with `closed`), `closedRows` and `state`. Exit 0 unchanged, 10 changed, 2 usage."
      }
    ]
  },
  "satisfies": [
    "review-log-watch"
  ],
  "requirements": {
    "runtime": [
      "bun"
    ],
    "network": true
  },
  "remedies": [
    {
      "host": "api.github.com",
      "none": "The issues are held by GitHub. Without it, pass `--issues` with a saved copy of the issues API answer; the check then compares the sheet against that copy."
    }
  ],
  "selection": {
    "when": "On every poll of a review-log watcher, before any agent work: the agent pass runs only when this reports `changed`.",
    "limits": "Reads one tab and one repository's issues; it never writes the sheet or GitHub. It sees an edit only in the watched headers, so the agent's own Green columns and the script's Grey ones never wake the watcher.",
    "cost": "One `gh api` call per 100 issues and one small JSON file; well under a second."
  }
}

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