Printing Press Polish

# PII Polish — Customer-PII Gate Playbook

**Goal:** clear the PII ledger so promote and publish gates pass. Every pending finding is either real PII (replace with a placeholder in source) or a justified non-PII match (accept in the ledger with pre-decision fields).

**Scope:** Phase 1 detectors are shape-only — order/transaction IDs, card-last-4, email, US phone, ZIP+4, postal-address. ASINs and standalone names are a future detector class pending spec-aware detection work. A passing gate is the floor, not "PII-clean."

```bash
cli-printing-press pii-audit <cli-dir>
```

The audit writes `<cli-dir>/.printing-press-pii-polish.json`. Promote and publish re-run the audit themselves, so the ledger header is the authority — they refuse if pending findings or gate failures remain.

When polish resolved a manuscripts run directory, run the audit with `--manuscripts-dir <run-dir>`. That adds only `<run-dir>/research.json` and `<run-dir>/research/*.md` to the scan and reports them as `.manuscripts/<run-id>/...` paths, matching the publish-staged tree.

## The accept contract

Every `status: "accepted"` entry must populate:

- **`category`** — one of `attribution`, `place_name`, `corporate_name`, `documentation_example`, `api_provider_data`, `synthetic_placeholder`, `other`. The closed enum forces a specific claim about *what shape of non-PII this is*.
- **`evidence_context`** — quote the surrounding 1-2 lines from the source. Lets a reviewer judge the category claim by reading only the ledger.
- **`note`** — free-form; required only when `category` is `other`.

```json
{
  "kind": "email",
  "file": "data.json",
  "line": 17,
  "matched_span": "alice@example.com",
  "status": "accepted",
  "category": "documentation_example",
  "evidence_context": "Inside README's 'Sample request' block, under a code fence demonstrating customer-email; reserved @example.com TLD."
}
```

If `category` and `evidence_context` can't be filled honestly, the finding isn't yet understood. Re-read the source and either fix it or pick a sharper category.

## Per-finding decision

For each pending finding, read 1-2 lines on either side of the match and pick one outcome:

| Outcome | When | What to do |
|---|---|---|
| **Fix in source** | Real customer value (captured order, sniff response, etc.) | Replace with the non-matching placeholder from the table below |
| `category: api_provider_data` | Vendor's published example (Stripe docs use `4242`, support@vendor.com, etc.) | Cite vendor docs URL or captured field name in `evidence_context` |
| `category: documentation_example` | Example value in README/SKILL prose teaching how a field works | Quote the documentation context |
| `category: synthetic_placeholder` | Already a standards-reserved synthetic (`user@example.com`, `+1-555-01xx`, `90210-1234`, `1 EXAMPLE WAY`) | Name the convention in `evidence_context` |
| `category: other` | Non-PII shape that matched (request ID, batch ID, version range hitting ZIP regex) | Required `note` names what the value actually is |

### Replacement placeholders

Use these to avoid re-flagging on the next audit:

| Detector | Placeholder (does not re-match) |
|---|---|
| `card-last-4` | `PII_CARD_LAST4_EXAMPLE` |
| `email` | `PII_EMAIL_EXAMPLE` |
| `phone-us` | `PII_PHONE_EXAMPLE` |
| `zip-plus-4` | `PII_ZIP_EXAMPLE` |
| `postal-address` | `PII_ADDRESS_EXAMPLE` |

When a downstream consumer (parser, schema validator) needs a valid-shape value, use the standards-reserved synthetics — `user@example.com`, `+1-555-0100`, `90210-1234`, `1 EXAMPLE WAY` — and accept the first audit finding as `synthetic_placeholder`. Subsequent audits preserve the accept.

### Detector-specific notes

- **`zip-plus-4`** has high false-positive rate. Request IDs, batch IDs, correlation IDs, and version ranges all match the shape. Most pending findings here resolve to `category: other` with a `note` naming the actual field, not real PII.
- **`postal-address`** matches Title-Case and ALL-CAPS street names