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, and account identifiers under account/party/customer-number keys. ASINs and standalone names are a future detector class pending spec-aware detection work. A passing gate is the floor, not "PII-clean."
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 ofattribution,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 whencategoryisother.
{
"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 |
account-id |
PII_ACCOUNT_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-4has high false-positive rate. Request IDs, batch IDs, correlation IDs, and version ranges all match the shape. Most pending findings here resolve tocategory: otherwith anotenaming the actual field, not real PII.postal-addressmatches Title-Case and ALL-CAPS street names with the common US suffixes. Lowercase real addresses are a known gap.card-last-4requires a context token (card/visa/ending in/last 4/4+ asterisks/x's). Bare 4-digit numbers don't match.account-idmatches an identifier-shaped value (8–17 digits, or 8–34 mixed letters and digits) under an account, party, or customer-number key, including nestedaccount.numberand names likedigitalAccountIdentifier. Short ids, sequential runs (12345678), all-zero runs, and doc tokens (acct_123,<accountId>,PII_ACCOUNT_EXAMPLE) do not match. Ordinary ids (id,page,userId) do not match.
Special cases
Generated files (DO-NOT-EDIT). Files carrying the // Generated by CLI Printing Press ... DO NOT EDIT. header are wiped on every regen — edits there don't survive. Trace upstream: the captured value came from a manuscript or spec file. Fix it at the source, regenerate, re-run the audit. The finding moves to the upstream file.
Manuscripts (.manuscripts/<runID>/). Highest-risk source — captured browser-sniff content is by construction where customer values entered. Acceptance for manuscript findings requires the explicit evidence_context-cited justification; "captured data" alone is not sufficient. When in doubt, replace the value in the manuscript file directly (it's local working state) and use a hand-authored fixture with synthetic values for any downstream tests.
Generated test fixtures (*_test.go, testdata/). Exempt from the audit by design — generated tests commonly carry standards-reserved or synthetic placeholder values, and rewriting them during polish creates churn without reducing customer-PII risk. Real PII in production code, config, README, and manuscript files remains in scope.
Tooling workspaces (.omc/, .claude/). Exempt from the audit at the CLI root — these are agent orchestration or scratch directories, not shippable printed-CLI content.
Vendor spec files at the CLI root (spec.yaml, spec.yml, spec.json). Exempt from the audit when the CLI was not browser-sniffed — these are the OpenAPI/internal source the operator passed to --spec, and vendor example: blocks (Stripe jenny@example.com, GitHub user-schema example phones) are documentation, not customer PII. The exemption does not apply when .printing-press.json records spec_source: sniffed (any nesting or key spelling) or the root spec itself has a top-level spec_source: sniffed. That spec was built from the printer's own session.
Vendor spec source archived under .manuscripts/. Files anywhere inside a .manuscripts/ subtree whose head bytes match an OpenAPI 2.x/3.x or Swagger 2.0 root-document marker are exempt — the operator archived the vendor's published spec source alongside research, and its example: blocks are documentation. The exemption is content-based, not glob-based, so per-resource subdir basenames like apps/calendars.json or vendor-named files like pushpress-v3.yaml are covered without an allowlist. HARs, session-state.json, hand-edited proofs, and any other non-spec content under .manuscripts/ stays in scope because the marker check fails on them.
Forbidden accept patterns
The binary enforces these via gate failures, not just convention:
- Identical rationale across 6+ findings — clustered by normalized
note+category. If you're stamping the samenoterepeatedly, fix the source content or file a follow-up to tighten the detector. - Wholesale-accept punt — when finding count is ≥ 10 and every finding is accepted with no source-level fixes, the all-accepted-no-fixes gate fires.
- Empty / placeholder
evidence_context—"ctx","n/a", single chars all pass theTrimSpacecheck mechanically but PR review will catch them. Quote the file.
Resumability
progress.last_processed_finding_id is an optional checkpoint to update after walking each finding. The audit's next: line uses it to resume mid-walk after a context flush. When absent, the audit resumes from the head.
Finding identity is (file, line, kind, normalized matched-span). Editing a file shifts line numbers — findings get fresh IDs and prior accepts no longer carry forward. This is by design: substantive churn deserves a fresh agent walk. Cosmetic edits (whitespace, case) don't change the ID.
Don't manually mark findings as fixed. A real source fix makes the finding disappear from the next audit; the delta line shows 1 resolved.
End-state checklist
-
cli-printing-press pii-audit <cli-dir> ${PII_ARGS[@]}summary readsno pending findings, noincomplete:block. Outside the polish shell, pass--manuscripts-dir <run-dir>when a manuscripts run was resolved. - Every accepted finding has
category+evidence_context.category: otheralso hasnote. - No 6+ accepts share a normalized
note+category. - Real PII fixes landed in source (
git diff). - If publishing into a public-library clone, add
.printing-press-pii-polish.jsonto that repo's.gitignore.