Public-comment change-sets
Bring a public review’s change-sets back in line with GitHub: open the primary issue of each change-set somebody has engaged with, link the other issues that discuss it, and re-render each issue’s change-set section from its changesets/CS-*.json record. The nightly half of what the folio’s public-comment workflow does on each issue event (github); check validates the records without writing.
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.
public-comment
Source: folio-assistant-core/skills/content/folio-document-adapter/public-comment.md.
input — folio-assistant-core/schemas/skills/public-comment/input.schema.json
| field | type | required | description |
|---|---|---|---|
operation | import \| import-narrative \| list \| triage \| reassign \| assign \| recommend \| decide \| incorporate \| duplicate \| withdraw \| github \| summary | yes | One task of public-comment.bpmn, or a read (list, summary). |
file | string | For import / import-narrative: the comment matrix (.xlsx), form export (.csv) or narrative text. | |
ref | string | The comment the operation acts on. | |
to | string | reassign/triage: a block or section label. assign: GitHub login(s), comma-separated. | |
code | accepted \| accepted-modified \| not-accepted \| noted \| deferred | recommend / decide: the decision code. | |
reason | string | decide: required for every code but accepted. | |
branch | string | decide / incorporate: the change-set branch. | |
pr | integer | decide / incorporate: the change-set pull request. | |
filter | object | list: narrow by status (or ‘open’), page, line, block, section, or unplaced. | |
stagingLinks | stagingLinks | The staging preview of the work under review, as the request for feedback carried it, so the reviewer opens the changed pages rather than rebuilding links. Rule: cat-harness sdlc/skills/sdlc-core/staging-review.md §”The deep-link rule”. |
output — folio-assistant-core/schemas/skills/public-comment/output.schema.json
| field | type | required | description |
|---|---|---|---|
changed | string[] | Comment refs written by the operation. | |
unplaced | string[] | import: refs whose citation resolved to no block, kept for triage. | |
refused | string[] | What was not done, and why: a tag from someone not in config.json, a transition the lifecycle does not allow. | |
comments | —[] | list: the matching public-comment/1.0.0 records. | |
stagingLinks | stagingLinks | The staging preview of the work this output asks a person to look at: one deep link per changed page, with the same page on main. Required whenever a preview exists; when it does not, say so in missing. Rule: cat-harness sdlc/skills/sdlc-core/staging-review.md §”The deep-link rule”. |
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 | operation | ChangeSetAction | yes | The command: reconcile (the nightly run), check (validate the records, write nothing) or github (one issue event, as the workflow does). | string · one of seed, propose, add, list, body, adopt, check, reconcile, github, install · A change-set verb: check or reconcile the records, or handle one GitHub issue event. |
| in | store | RepoPath | The record’s directory in the repository. Default review/public-comment. | string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments. | |
| out | changesets | RepoPath | The updated changesets/CS-*.json records under the store; the issues are updated on GitHub. | 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 |
|---|---|---|---|
| Draft, review and publish | Release for public comment | Public review (commenters, review committee, editor) | public-comment |
| Make a decided public comment change | Edit the document as decided, on a feature branch | Author (human or agentic) | public-comment |
| Make a decided public comment change | QA gate: check dispositions against the people and the pull request | QA reviewer (independent) | public-comment |
| Make a decided public comment change | Mark incorporated when the change set merges | Change set — feature branch and staging | public-comment |
| Release a draft for public comment | Agree the release date and comment period | Review committee and editor | public-comment |
| Release a draft for public comment | Set up the comment channels, with instructions and links | Editor | public-comment |
| Release a draft for public comment | Write the announcement, with links | Editor | public-comment |
| Release a draft for public comment | Distribute to the public | Review committee and editor | public-comment |
| Release a draft for public comment | Public comment on the release | Editor | public-comment |
| Public comment on a review draft | Ingest and place each comment | Intake agent | public-comment |
| Public comment on a review draft | Triage: confirm the anchor, type and priority | Review coordinator | public-comment |
| Public comment on a review draft | Propose change-sets, as records with no issue yet | Intake agent | public-comment |
| Public comment on a review draft | Agree each change-set’s requirements on its issue | Review committee | public-comment |
| Public comment on a review draft | Re-route to another committee | Review committee | public-comment |
| Public comment on a review draft | Assign to committee members | Review coordinator | public-comment |
| Public comment on a review draft | Recommend a decision, with a rationale | Review committee | public-comment |
| Public comment on a review draft | Decide, weighing the recommendations | Editor | public-comment |
| Public comment on a review draft | Make the change, check it and merge it | Editor | public-comment |
| Public comment on a review draft | Record the withdrawal | Public commenter | public-comment |
| Data sharing agreement document life cycle | Public comment on the template | Public review (commenters, review committee, editor) | public-comment |
| DTH authoring | Import into review/wg-comment and form change sets | Editor | public-comment |
| DTH authoring | 5 · Open public comment | Editor | public-comment |
| DTH authoring | Disposition comments and apply change sets | Editor | public-comment |
How it is deployed and reached
- Command line. From the repository root:
bun run folio-assistant-core/scripts/public-comment-changesets.ts. - GitHub Actions. 3 workflow line(s) run its command:
| workflow | line | |
|---|---|---|
folio-assistant-core/.github/workflows/public-comment-check.yml | 47 | run: bun run folio-assistant-core/scripts/public-comment-changesets.ts check --store "$STORE" |
folio-assistant-core/.github/workflows/public-comment-check.yml | 62 | run: bun run folio-assistant-core/scripts/public-comment-changesets.ts reconcile --store "$STORE" |
folio-assistant-core/.github/workflows/public-comment.yml | 81 | run: bun run folio-assistant-core/scripts/public-comment-changesets.ts github --store "$STORE" --event "$GITHUB_EVENT_PATH" |
As an API: its operation in the OpenAPI document and the MCP tool list of its layer.
| install | none |
| runtime | bun, gh |
| network | yes |
When a host it reaches is refused:
| host / error | remedy |
|---|---|
github.com | none: The issues live on GitHub; offline, check still validates the records and nothing is opened or re-rendered. |
| when to choose it | |
|---|---|
| when | Change-set records and their GitHub issues may have drifted: a recommendation made from the CLI, an issue edited by hand, or a missed workflow run. |
| limits | Writes only under the store and to issues of the current repository. One run at a time, like the workflow it backs. |
| cost | Seconds plus one GitHub API call per change-set that has issues. |
What it is made of
| role | file | |
|---|---|---|
| definition | folio-assistant-core/tools/public-comment-changesets/public-comment-changesets.ts | |
| script | folio-assistant-core/scripts/public-comment-changesets.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/public-comment-changesets.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/public-comment-changesets.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": "public-comment-changesets",
"title": "Public-comment change-sets",
"description": "Bring a public review's change-sets back in line with GitHub: open the primary issue of each change-set somebody has engaged with, link the other issues that discuss it, and re-render each issue's change-set section from its `changesets/CS-*.json` record. The nightly half of what the folio's public-comment workflow does on each issue event (`github`); `check` validates the records without writing.",
"install": {
"none": true
},
"invoke": {
"shell": "bun run folio-assistant-core/scripts/public-comment-changesets.ts"
},
"io": {
"inputs": [
{
"name": "operation",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/ChangeSetAction",
"description": "The command: `reconcile` (the nightly run), `check` (validate the records, write nothing) or `github` (one issue event, as the workflow does).",
"required": true,
"arg": {
"positional": 0
}
},
{
"name": "store",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
"description": "The record's directory in the repository. Default `review/public-comment`.",
"required": false,
"arg": {
"flag": "--store"
}
}
],
"outputs": [
{
"name": "changesets",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
"description": "The updated `changesets/CS-*.json` records under the store; the issues are updated on GitHub."
}
]
},
"satisfies": [
"public-comment"
],
"requirements": {
"runtime": [
"bun",
"gh"
],
"network": true
},
"remedies": [
{
"host": "github.com",
"none": "The issues live on GitHub; offline, `check` still validates the records and nothing is opened or re-rendered."
}
],
"selection": {
"when": "Change-set records and their GitHub issues may have drifted: a recommendation made from the CLI, an issue edited by hand, or a missed workflow run.",
"limits": "Writes only under the store and to issues of the current repository. One run at a time, like the workflow it backs.",
"cost": "Seconds plus one GitHub API call per change-set that has issues."
}
}