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 [1..1]output [1..1]filter [0..1]pages [0..*]pages [0..*]stagingLinks [0..1]stagingLinks [0..1]public-comment«skill»public-commentinput : PublicCommentInput [1..1]output : PublicCommentOutput [1..1]PublicCommentInput«json-schema»PublicCommentInputoperation : "import" | "import-narrative" | "list" | "tr… [1..1]file : string [0..1]ref : string [0..1]to : string [0..1]code : "accepted" | "accepted-modified" | "not-accepted"… [0..1]reason : string [0..1]branch : string [0..1]pr : integer [0..1]filter : PublicCommentInput.filter [0..1]stagingLinks : stagingLinks [0..1]PublicCommentInput.filter«json-schema»PublicCommentInput.filterstatus : string [0..1]page : integer [0..1]line : integer [0..1]block : string [0..1]section : string [0..1]unplaced : boolean [0..1]stagingLinks.pages«json-schema»stagingLinks.pagestitle : string [1..1]before : string [0..1]after : string [0..1]summary : string [0..1]stagingLinks«json-schema»stagingLinksbranch : string [1..1]slug : string [1..1]branchUrl : string [1..1]pr : integer [0..1]mainBaseUrl : string [1..1]stagingBaseUrl : string [1..1]pages : stagingLinks.pages[] [0..*]missing : string[] [0..*]PublicCommentOutput«json-schema»PublicCommentOutputchanged : string[] [0..*]unplaced : string[] [0..*]refused : string[] [0..*]comments : unknown[] [0..*]stagingLinks : stagingLinks [0..1]stagingLinks.pages«json-schema»stagingLinks.pagestitle : string [1..1]before : string [0..1]after : string [0..1]summary : string [0..1]stagingLinks«json-schema»stagingLinksbranch : string [1..1]slug : string [1..1]branchUrl : string [1..1]pr : integer [0..1]mainBaseUrl : string [1..1]stagingBaseUrl : string [1..1]pages : stagingLinks.pages[] [0..*]missing : string[] [0..*]

input — folio-assistant-core/schemas/skills/public-comment/input.schema.json

fieldtyperequireddescription
operationimport \| import-narrative \| list \| triage \| reassign \| assign \| recommend \| decide \| incorporate \| duplicate \| withdraw \| github \| summaryyesOne task of public-comment.bpmn, or a read (list, summary).
filestringFor import / import-narrative: the comment matrix (.xlsx), form export (.csv) or narrative text.
refstringThe comment the operation acts on.
tostringreassign/triage: a block or section label. assign: GitHub login(s), comma-separated.
codeaccepted \| accepted-modified \| not-accepted \| noted \| deferredrecommend / decide: the decision code.
reasonstringdecide: required for every code but accepted.
branchstringdecide / incorporate: the change-set branch.
printegerdecide / incorporate: the change-set pull request.
filterobjectlist: narrow by status (or ‘open’), page, line, block, section, or unplaced.
stagingLinksstagingLinksThe 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

fieldtyperequireddescription
changedstring[]Comment refs written by the operation.
unplacedstring[]import: refs whose citation resolved to no block, kept for triage.
refusedstring[]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.
stagingLinksstagingLinksThe 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.

porttyperequireddescriptionconstraint
inoperationChangeSetActionyesThe 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.
instoreRepoPathThe 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.
outchangesetsRepoPathThe 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:

processsteplanevia skill
Draft, review and publishRelease for public commentPublic review (commenters, review committee, editor)public-comment
Make a decided public comment changeEdit the document as decided, on a feature branchAuthor (human or agentic)public-comment
Make a decided public comment changeQA gate: check dispositions against the people and the pull requestQA reviewer (independent)public-comment
Make a decided public comment changeMark incorporated when the change set mergesChange set — feature branch and stagingpublic-comment
Release a draft for public commentAgree the release date and comment periodReview committee and editorpublic-comment
Release a draft for public commentSet up the comment channels, with instructions and linksEditorpublic-comment
Release a draft for public commentWrite the announcement, with linksEditorpublic-comment
Release a draft for public commentDistribute to the publicReview committee and editorpublic-comment
Release a draft for public commentPublic comment on the releaseEditorpublic-comment
Public comment on a review draftIngest and place each commentIntake agentpublic-comment
Public comment on a review draftTriage: confirm the anchor, type and priorityReview coordinatorpublic-comment
Public comment on a review draftPropose change-sets, as records with no issue yetIntake agentpublic-comment
Public comment on a review draftAgree each change-set’s requirements on its issueReview committeepublic-comment
Public comment on a review draftRe-route to another committeeReview committeepublic-comment
Public comment on a review draftAssign to committee membersReview coordinatorpublic-comment
Public comment on a review draftRecommend a decision, with a rationaleReview committeepublic-comment
Public comment on a review draftDecide, weighing the recommendationsEditorpublic-comment
Public comment on a review draftMake the change, check it and merge itEditorpublic-comment
Public comment on a review draftRecord the withdrawalPublic commenterpublic-comment
Data sharing agreement document life cyclePublic comment on the templatePublic review (commenters, review committee, editor)public-comment
DTH authoringImport into review/wg-comment and form change setsEditorpublic-comment
DTH authoring5 · Open public commentEditorpublic-comment
DTH authoringDisposition comments and apply change setsEditorpublic-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:
workflowline
folio-assistant-core/.github/workflows/public-comment-check.yml47run: bun run folio-assistant-core/scripts/public-comment-changesets.ts check --store "$STORE"
folio-assistant-core/.github/workflows/public-comment-check.yml62run: bun run folio-assistant-core/scripts/public-comment-changesets.ts reconcile --store "$STORE"
folio-assistant-core/.github/workflows/public-comment.yml81run: 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.

installnone
runtimebun, gh
networkyes

When a host it reaches is refused:

host / errorremedy
github.comnone: The issues live on GitHub; offline, check still validates the records and nothing is opened or re-rendered.
when to choose it
whenChange-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.
limitsWrites only under the store and to issues of the current repository. One run at a time, like the workflow it backs.
costSeconds plus one GitHub API call per change-set that has issues.

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

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