Folio ChangeSet

What changed in a folio between two git refs, block by block: each block added, removed, or changed — and for a changed block, every aspect that applies (renamed, prose, manifest, moved). Keyed on the block label, which the id-unique / id-stable QA criteria guard, not on file paths.

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.

diff

Show per-block content changes with viewer links, changelog, and undo impact analysis

Source: folio-assistant-core/skills/content/content-lifecycle-ext/diff.md.

The skill declares no I/O contract (schemas/skills/diff/{input,output}.schema.json).

staging-review

Staging preview and before/after comparison for content review. Takes one optional string — what the reader wants to look at, in their own words — and returns a list of URLs, each looked up in the publish ref, with what is published at it and what to review there. Provides before (MAIN) and after (branches/) pairs so reviewers can compare rather than guess. Used by the CRDM feature development workflow, content authoring review sessions, and whenever a staging preview deploys or someone asks to see it.

Source: cat-harness/skills/ui/ui-core/staging-review.md.

Also satisfied by: paper-preview.

input [1..1]output [1..1]pages [0..*]stagingLinks [1..1]staging-review«skill»staging-reviewinput : StagingReviewInput [1..1]output : StagingReviewOutput [1..1]StagingReviewInput«json-schema»StagingReviewInputask : string [0..1]branch : string [0..1]pr : integer [0..1]StagingReviewOutput«json-schema»StagingReviewOutputnarrative : string [1..1]startHere : string [0..1]stagingLinks : stagingLinks [1..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 — cat-harness/schemas/skills/staging-review/input.schema.json, https://litlfred.github.io/folio-assistant/cat-harness/skills/staging-review/input.schema.json

fieldtyperequireddescription
askstringWhat the reader wants to look at, verbatim. Absent: the whole preview, every page the branch changed.
branchstring
printeger

output — cat-harness/schemas/skills/staging-review/output.schema.json, https://litlfred.github.io/folio-assistant/cat-harness/skills/staging-review/output.schema.json

fieldtyperequireddescription
narrativestringyesWhat a reader of the site will now see or do differently, and why, before any link.
startHerestringThe one page to open first.
stagingLinksstagingLinksyes

Inputs and outputs

Each port names a shared type by IRI, so two Tools for one skill can be checked for interchangeability.

porttyperequireddescriptionconstraint
infolioRepoPathyesThe folio’s folio graph directory, relative to the repository — what <slug>.json declares for it, usually folio/.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
inbaseBranchThe ref compared against. Default origin/main. An unresolvable base is an ERROR, never an empty ChangeSet.string · pattern ^[A-Za-z0-9][A-Za-z0-9._/-]*$ · A git branch name
inheadBranchThe ref under review, or worktree (the default) for the files on disk, uncommitted edits included.string · pattern ^[A-Za-z0-9][A-Za-z0-9._/-]*$ · A git branch name
inoutRepoPathWhere to write the JSON. Absent: stdout.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
intext-outRepoPathAlso write changeset-text.json: the prose, source and rendered, of every block the ChangeSet lists, on each side that has it. The review page’s diff renderers read it.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
outchangesetRepoPathA folio-changeset/v1 document. 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
Review taskClassify what changedReviewer / SMEstaging-review
CRDM Phase 6 — implement, MVP, acceptancePost summary to issueAgentstaging-review
CRDM Phase 6 — implement, MVP, acceptanceShare MVP with stakeholdersBA / Feature Requestorstaging-review
Code change and reviewCommit, push, open the PRAuthoring agentstaging-review
Code change and reviewReview the changeCode reviewerstaging-review
Staging a feature branch preview, and taking it downComment the preview URL on the PRCI/CD Pipelinestaging-review
Staging a feature branch preview, and taking it downPost the retention notice on the PRCI/CD Pipelinestaging-review
Adopting an upstream version bumpReview the MVP against what we bind toReviewer / SMEstaging-review
Questionnaire wireframe reviewAsk for review with deep linksFHIR modellerstaging-review
Committee review of a content changeCompare main vs stagingReview Committeestaging-review
Committee review of a content changeSlice the change and assign reviewersReview Coordinatorstaging-review
Content Change and ReviewReview staged renderingContent Authorstaging-review
Content Change and ReviewRequest further revisionsContent Authorstaging-review
Content Change and ReviewSubmit to review committeeContent Authorstaging-review
Draft, review and publishCirculate the draftPublication managerstaging-review
Draft, review and publishReview the draft publicationReview team (content · QC · technical officer)staging-review
Draft, review and publishClinical or scientific sign-offClinical / scientific SMEsstaging-review
Make a decided public comment changeReview the change set on its staging previewChange set — feature branch and stagingstaging-review
Review and publish a folioReview and record feedbackReviewerstaging-review
SMART Guideline end to endReview each L2 asset (before / after if adapted)Human adjudicatorsstaging-review
SMART Guideline end to endReview each L3 asset (before / after if adapted)Human adjudicatorsstaging-review
SMART Guideline end to endAdjudicate the L4 wireframes and applicationHuman adjudicatorsstaging-review
Classify and code contentStage codings, warnings and exclusions for reviewAuthoring agentstaging-review
L2 component edit and reviewAsk for review with staging deep linksAuthoring agentstaging-review

How it is deployed and reached

  • Command line. From the repository root: bun run folio-assistant-core/schemas/changeset.ts.
  • GitHub Actions. 2 workflow line(s) run its command:
workflowline
.github/workflows/folio-staging.yml197if [ -f "$PLATFORM_DIR/folio-assistant-core/schemas/changeset.ts" ]; then
.github/workflows/folio-staging.yml398bun run "$PLATFORM_DIR/folio-assistant-core/schemas/changeset.ts" \\

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

installnone
runtimebun, git, tar
networkno
when to choose it
whenA reviewer, or the review page, needs to know which BLOCKS a branch changed — not which files. Use it before building a before/after table, a change heat map, or a per-block diff report.
limitsReads manifests as text and never executes the base ref, so a section whose blocks are computed rather than listed is invisible to it. An unlabelled block is identified by its slug, so renaming its file reads as removed plus added. Rendered assets (SVGs) are not compared.
costSeconds for a few thousand blocks: one git archive per committed ref, then a text walk. No network.

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-changeset.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-changeset.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-changeset",
  "title": "Folio ChangeSet",
  "description": "What changed in a folio between two git refs, block by block: each block added, removed, or changed — and for a changed block, every aspect that applies (renamed, prose, manifest, moved). Keyed on the block label, which the `id-unique` / `id-stable` QA criteria guard, not on file paths.",
  "install": {
    "none": true
  },
  "invoke": {
    "shell": "bun run folio-assistant-core/schemas/changeset.ts"
  },
  "io": {
    "inputs": [
      {
        "name": "folio",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "The folio's `folio` graph directory, relative to the repository — what `<slug>.json` declares for it, usually `folio/`.",
        "required": true,
        "arg": {
          "flag": "--folio"
        }
      },
      {
        "name": "base",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Branch",
        "description": "The ref compared against. Default `origin/main`. An unresolvable base is an ERROR, never an empty ChangeSet.",
        "required": false,
        "arg": {
          "flag": "--base"
        }
      },
      {
        "name": "head",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Branch",
        "description": "The ref under review, or `worktree` (the default) for the files on disk, uncommitted edits included.",
        "required": false,
        "arg": {
          "flag": "--head"
        }
      },
      {
        "name": "out",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "Where to write the JSON. Absent: stdout.",
        "required": false,
        "arg": {
          "flag": "--out"
        }
      },
      {
        "name": "text-out",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "Also write `changeset-text.json`: the prose, source and rendered, of every block the ChangeSet lists, on each side that has it. The review page's diff renderers read it.",
        "required": false,
        "arg": {
          "flag": "--text-out"
        }
      }
    ],
    "outputs": [
      {
        "name": "changeset",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "A `folio-changeset/v1` document. Its one-line summary goes to stderr."
      }
    ]
  },
  "satisfies": [
    "diff",
    "staging-review"
  ],
  "requirements": {
    "runtime": [
      "bun",
      "git",
      "tar"
    ],
    "network": false
  },
  "selection": {
    "when": "A reviewer, or the review page, needs to know which BLOCKS a branch changed — not which files. Use it before building a before/after table, a change heat map, or a per-block diff report.",
    "limits": "Reads manifests as text and never executes the base ref, so a section whose blocks are computed rather than listed is invisible to it. An unlabelled block is identified by its slug, so renaming its file reads as removed plus added. Rendered assets (SVGs) are not compared.",
    "cost": "Seconds for a few thousand blocks: one `git archive` per committed ref, then a text walk. No network."
  }
}

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