# Routine Document Publishing — QA Suite

Five browser-based tools that automate the accessibility/compliance review, CMS-gatekeeping,
conversion, and final QA of routine publications (legal texts, annual reports, and similar
"we don't touch the content, we just publish it correctly" documents). Four match the original
proposal 1:1 (Prep-Check, Gatekeeper, Converter, Validator); a fifth, experimental "Beta
Auto-Resolve" tool goes further than Gatekeeper's own careful auto-fix and takes a best-guess,
fully-logged position on every blocker — see "The beta tool" below.

Built to satisfy two hard constraints from the underlying proposal:

1. **No document content ever leaves the local machine.** Every tool is a static HTML file that
   runs entirely client-side — no server, no upload, no network call. Open `docs/AUDIT.md` and
   search any tool's source for `fetch(`, `XMLHttpRequest`, or `<img src="http`: there are none.
   This is provable by reading the file, not just a policy promise.
2. **QA must have virtually zero mistakes.** The pipeline is sequenced so each tool's output is a
   hard precondition for the next — the Converter (Tool 3) will not run against a document that
   hasn't cleared the Gatekeeper (Tool 2), and it enforces that in code, not just as a documented
   process step.

## How to run any tool

No install, no build step, no server. Just open the file:

```
tools/01-prep-check/index.html
tools/02-gatekeeper/index.html
tools/03-converter/index.html
tools/04-validator/index.html
tools/05-beta-autoresolve/index.html
```

Double-click, or drag into an open browser tab. Each tool loads its sibling `.js`/`.css` files
from `tools/shared/` via plain relative `<script src>`/`<link>` tags — that works fine from a
`file://` URL (unlike `fetch`/`XHR`, which browsers block cross-origin for local files). Keep the
whole `tools/` folder together when copying it anywhere (a shared drive, a zipped attachment, an
internal wiki page) — don't detach a tool's `index.html` from `tools/shared/`.

## The pipeline

```
Client submits .docx
        │
        ▼
┌───────────────────┐   soft/editorial findings → feedback to client. Full heading
│ 1 · Prep-Check     │   outline, sentence case, italics usage, stray/placeholder text.
│  + Beta Fixer      │   Beta Fixer one-click applies the mechanical fixes (+ opt-in
└─────────┬──────────┘   best-guess sentence-case rewrite) → fixed .docx + a log.
          ▼
┌───────────────────┐   hard CMS-compatibility gate. BLOCKS on custom styles,
│ 2 · Gatekeeper     │   dynamic fields, missing alt text, tracked changes, etc.
│  + Flatten         │   "Flatten for Coding" auto-fixes the mechanical subset,
└─────────┬──────────┘   outputs a new .docx + changelog. Re-run until clear.
      ↓        ↘
      │         ┌───────────────────┐  optional, experimental: best-guess auto-
      │         │ 5 · Beta          │  resolves EVERY blocker (footnotes, outline
      │         │   Auto-Resolve    │  numbering, equations, nested tables, custom
      │         └─────────┬─────────┘  styles included) → fixed .docx + changelog.
      │                   │
      ▼◀──────────────────┘            (either path can feed into Converter once clear)
┌───────────────────┐   refuses to run if Gatekeeper's hard blockers are still
│ 3 · Converter      │   present (checked in code, not just by process).
└─────────┬──────────┘   Word → semantic HTML via style-map.js.
          ▼
     [ CMS coding / publishing — outside this suite ]
          │
          ▼
┌───────────────────┐   source .docx vs. published HTML, item-by-item, with a
│ 4 · Validator      │   zero-tolerance pass on every figure (currency, %, dates,
└────────────────────┘   numbers) — any figure mismatch is always a hard fail.
```

Tools 1 and 2 are advisor-facing; Tools 3 and 4 are coder/publisher-facing, matching the
four-tool split in the original proposal. Tool 5 is an optional, opt-in branch off Gatekeeper —
see "The beta tool" below before using it on anything real.

## The beta tools

Two "beta" surfaces exist, both opt-in and both logged in full: Prep-Check's **Beta Fixer** panel
(fixes its own soft findings — spacing, quote style, blank paragraphs, and an opt-in best-guess
sentence-case rewrite) and the standalone **Tool 5 · Beta Auto-Resolve** (takes a best-guess
position on every Gatekeeper hard blocker, including the ones Gatekeeper's own "Flatten"
deliberately leaves for a human — footnotes, outline numbering, equations, nested tables, custom
styles, text boxes). Both exist because 100%-manual review doesn't scale to hundreds of documents
a year, but neither is a substitute for reading its output log — every decision either one makes
is itemized, and several (sentence case without a real proper-noun list, custom-style name
guessing, sequential-numbering assumptions) are explicitly flagged as guesses that need a human
to confirm, not silent fixes.

## Repo layout

```
tools/
  shared/            docx-io.js, diff-utils.js, ui-kit.css, ui-kit.js — used by all five tools
  01-prep-check/      Tool 1 (checks.js + betafix.js)
  02-gatekeeper/      Tool 2 (checks.js + flatten.js)
  03-converter/       Tool 3 (style-map.js ← the CMSification file, + convert.js)
  04-validator/       Tool 4 (inventory.js + compare.js)
  05-beta-autoresolve/ Tool 5 — BETA (autoresolve.js; reuses Tool 2's checks.js + flatten.js)
docs/
  CMSIFICATION.md     what the technical team needs to gather/edit to make this org-specific
  AUDIT.md            findings from auditing the two uploaded prototypes, and what changed
```

## What's generic vs. what needs your CMS

Everything above produces **correct, semantic, standards-compliant HTML** — but it doesn't yet
know your CMS's actual component markup (WET table classes, callout box structure, the real page
shell, etc.). That customization lives entirely in `tools/03-converter/style-map.js`, which is
deliberately the only file that should need real editing for CMSification. Start with
`docs/CMSIFICATION.md`.