---
name: blueprint-polish-polish
description: "Polish the next file on the list to the house style without changing what it says, keep the original, and check it."
---

# Polish one file

Take the **first** file in `.blueprint/polish.json` whose status is `"todo"`. Polish that file only; the
next round takes the next one.

## First, keep the original

Copy the file to `.blueprint/originals/<the same path>` before changing anything (create the folders).
The check compares against it, and it is how the person undoes a change.

## What may change, and what may not

The document must still **say the same thing**. What changes is how it is said.

- **May change**: wording, sentence length and endings, spacing, spelling to the team's terms, splitting a
  long sentence or paragraph, removing padding.
- **May not change** — the check compares these with the original and fails on any difference:
  - the headings, in order and word for word (other documents link to them);
  - the articles, sections and items chaff reads as the document's structure (`chaff tree`), so a
    reference such as "第3条第2項" or "Section 4.2" still points at the same place;
  - code blocks, byte for byte;
  - link targets.
- Never add a fact, a number, a date or a name that is not in the original. Never drop one.

Follow `STYLE.md` when the answer `scope` includes the guide; otherwise, and when there is no `scope`, fix only what chaff reports.

## Check it

`sh <base pack>/checks/chaff.sh <the file>` — with the same `--genre` as the survey when the answer `kind`
gives one (see `<usecase pack>/kinds.json`) — must report no warning or error, except the ones you set aside.
Set a finding aside — never change the meaning to satisfy a rule — in one of two cases, by adding it to the
file's entry in `.blueprint/polish.json`:

```json
{ "file": "guide.md", "before": 4, "status": "done",
  "dismissed": [{ "rule": "max-sentence-length", "line": 12, "because": "meaning", "why": "条文の引用で、切ると原文と違ってしまう" }] }
```

- `"because": "wrong"` — chaff misread the text (a heading it took for a sentence, a name it took for jargon).
  Each one becomes a draft report to chaff in the report step.
- `"because": "meaning"` — chaff is right, but fixing it would change what the document says.

Only a file you mark `"done"` may set findings aside. `rule` and `line` are exactly as chaff reports them now,
one dismissal per finding (two findings of a rule on one line need two); the check refuses a dismissal chaff does not report,
so update the line if your other edits moved it. `why` is one line the person can judge. Set aside only what
you cannot fix — the report shows every one to the person.

If the file cannot be polished at all without changing what it says, restore it from the original, set its
status to `"skipped"` and write a `note` saying why. Otherwise set it to `"done"`.

## Done when

`node <usecase pack>/checks/targets.mjs verify` (with `BLUEPRINT_BASE` and `BLUEPRINT_USECASE` set to the
pack folders from your prompt) passes. Run `verify`, never `progress`: `progress` is the executor's check at
the end of the round and records how many files were finished, so running it yourself makes the real check
fail.