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.
| port | type | required | description | constraint | |
|---|---|---|---|---|---|
| in | repo | RepoPath | yes | The 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. |
| in | sheet | RepoPath | yes | 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. | string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments. |
| in | state | RepoPath | yes | The 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. |
| in | issues | RepoPath | Issues 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. | |
| in | author | RepoPath | Only 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. | |
| in | sheetHash | RepoPath | 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. | string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments. | |
| in | label | RepoPath | 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). | string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments. | |
| in | skipLabel | RepoPath | The 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. | |
| out | result | RepoPath | 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. | 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 |
|---|---|---|---|
| Record agent step | Read back Agentic status and Staging review | Authoring agent | review-log-watch |
| Review-log watch | Read the Contributor Feedback tab | Log watcher (authoring agent) | review-log-watch |
| Review-log watch | Run the review-log-watch check | Log watcher (authoring agent) | review-log-watch |
| Review-log watch | Hand new feedback to the row’s agent; take over stalled rows | Log watcher (authoring agent) | review-log-watch |
| Review-log watch | Append rows for new issues; hide closed ones | Log watcher (authoring agent) | review-log-watch |
| Review-log watch | Accept the new state | Log 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.
| install | none |
| runtime | bun |
| network | yes |
When a host it reaches is refused:
| host / error | remedy |
|---|---|
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. |
| when to choose it | |
|---|---|
| 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. |
What it is made of
| role | file | |
|---|---|---|
| definition | folio-assistant-core/tools/review-log-watch/review-log-watch.ts | |
| script | folio-assistant-core/tools/review-log-watch/watch.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/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."
}
}