Change check mode

Change check compares one page as it is on the current branch with the same page on a base ref (origin/main unless the user names another) and gives the...

Change check compares one page as it is on the current branch with the same page on a base ref (origin/main unless the user names another) and gives the page owner a go/no-go report. It is a final sanity check, not a review: it asks what was lost, what was added without sign-off and how the page reads, and it never rates the page. It rewrites nothing and records nothing.

Use it when someone has changed a page and the owner wants to know whether it is safe to ship. It works on any change, whether the kit or a person made it. It is a different task from Review-only, which rates one version against the rubric.

Request

PartRule
PageOne page path, such as src/pages/components/accordion/index.mdx.
Base refOptional. Default origin/main. Any ref the user names (a branch, a tag or a commit) is accepted.
Owner’s concernsOptional free text. Pass it to the product owner verbatim.

Run one page per request. If the user names several pages, say that Change check takes one at a time and ask which to start with. If the request does not make clear whether the user wants a rating or a go/no-go comparison, ask, as the router requires.

Execute

  1. Run node authoring-kit/scripts/prepare-change-check.mjs --source=<page> [--base=<ref>]. It resolves the ref to a commit locally (it never fetches, so a stale origin/main is the user’s to refresh), reads the page at that commit, copies the working-tree page beside it, writes the inventory and allocates the run. Stop on ok: false and report the error. Then act on decision:
    • new-page: the page does not exist at the base. Say there is nothing to compare, offer a Review-only run, and stop. Nothing was allocated.
    • unchanged: the page is identical to the base. Say so and stop. Nothing was allocated.
    • ready: continue.
  2. Read the product owner brief and dispatch one fresh authoring-kit-po. Supply the baseline, proposed and inventory paths, the concerns if any, the first of reportPaths, and a link to the product owner workflow. Never fork the PM conversation, and never tell the product owner the ref, the commit, how either version was produced or scored, or anything else the brief forbids. Whether the working tree has uncommitted edits (workingTreeDirty) goes in the PM’s report, not the brief.
  3. Await the returned path and accept it under the brief. Recompute the source page’s SHA-256 and compare it with proposedHash. A changed page makes the check stale: say so, and do not present the report as current.
  4. Report to the user:
    • the verdict and the product owner’s reason for it, in the product owner’s own words;
    • the headline findings in a few lines: count the rows in the table of things to check by kind, then name the most serious. The report is the record, so do not retell it;
    • the path to the report;
    • what was compared: the base ref and its commit (first nine characters), the branch’s HEAD, and workingTreeDirty when true, so the user knows exactly what was read;
    • what the product owner could not check;
    • that nothing was committed or recorded, the live page and ledger are untouched, and the run is disposable cache. Do not add a verdict, a rating or a finding of your own. If the user disagrees with the report, the report stands and the user decides.

Run state and output

Everything lives in the cache document root, .authoring-kit-cache/documents/<source-directory>/<document-key>/change-checks/<run-id>/: baseline.<extension> (the page at the base commit), proposed.<extension> (the working-tree page), inventory.md, and the report, po-report.md. Nothing is committed and there is no manifest, schema or ledger entry. A Change check is a temporary aid to a go/no-go decision. It is not a rating and never appears in reviews/, so Rebase cannot mistake it for one.

The run ID is the UTC start time as YYYYMMDD-HHmmss, with the first free -02, -03… suffix on a collision. A retry gets a new run ID. Old run folders are removed by npm run clean, or by hand.

Interrupted or invalid runs

If the product owner fails, returns the wrong path or an incomplete report after the one correction, or the page changes during the run, tell the user and stop. Never write the report yourself, never relay a partial report as complete, and never fall back to a Review-only run without being asked.

See also