claricle 0.1.0 → 0.2.0

data/TODO.plan/03-conform.md

@@ -0,0 +1,208 @@
+# 03 — Conform: unified reports, `Claricle.conform?`, batch helper
+
+Can start: after 02. D16 (PDF scope), D22 (EPS/PS) and D23 (pre-pass)
+settle what this item builds.
+
+## Problem
+
+Each delegate reports validity in a different shape (typed issues,
+error strings, exceptions, or parse-error lists). The issue demands one
+typed `Report` with uniform `Issue{severity, code, message, location}`
+across every format that has a conformance basis, a module-level API,
+and a batch-capable CLI
+command that exits 1 on nonconformance.
+
+## Design
+
+Mapping layer per handler — `location` is nullable throughout;
+synthetic stable codes where upstream has none; never invent
+coordinates:
+
+| Delegate result | → Issue mapping |
+|---|---|
+| png_conform, **not** via `validate_file` | Build `Readers::FullLoadReader.new(path)`, pass it to `ValidationService.new(reader, path)`, call `validate`, then read **all three buckets — `context.all_errors`, `all_warnings`, `all_info`**. Location lives on the **context object only**: both `validate_file` and `result.validation_result.errors` return `chunk_type: nil, chunk_offset: nil` for the same input. `all_errors` alone silently drops warnings and info, which would break D8's tri-state and `--strict`. Measured error shape: `{chunk_type: "IDAT", message: "CRC error in IDAT chunk", severity: :error, offset: 33}`. Map `severity` as-is, `location: {chunk: chunk_type, byte_offset: offset}` (offset may be nil, e.g. a missing IEND). **`byte_length` has no source here** — png_conform reports a start offset only, so the issue's "byte range" is delivered as offset-plus-chunk for PNG, and `byte_length` stays nil unless the pre-pass (D23) computes it from the chunk header, which it can. `code` synthesized stably since there is no upstream type. **Never use `validate_file`** — it returns a `FileAnalysis` with chunk and offset discarded. See D23: this path misses duplicate `IHDR`/`IEND` and trailing bytes entirely |
+| svg_conform `ValidationIssue` | Severity is `severity || type` — `ErrorTracker#add_error` hardcodes `type: :error`, and `severity` was measured **nil** on some issues, so neither field alone is reliable. Normalize `:validity_error` to `error`. Collect errors, warnings **and** validity errors, not just one bucket. `code: requirement_id`. `line` and `column` were nil on every issue measured, so `location` is usually nil; populate only when present. Run under the `base` profile (D21), and call `Profiles.clear_cache!` or enumerate eagerly — `available_profiles` collapses to just the last-loaded profile after any validation. Note UTF-32 input was measured passing every profile silently, so the structural pre-pass (D23) must settle encoding before profile validation runs — but note D23: `base` returns 0 errors for raw binary, so it cannot stand alone |
+| emf | `Emf.parse` → `Metafile` exposing `ok?` and `errors`. **`ok?` is not sufficient on its own**, and truncation is the sharpest case: of the 164 truncations of `valid.emf` that parse without raising, **16 report `ok? == true`** (measured 2026-09-08, same sweep as the allowlist figures below). `after_eof.emf` shows it without truncation too — bytes past the EOF record, measuring `ok? == true, errors == [], records == 16`, the same numbers as the intact file. (Re-measured 2026-09-08. The earlier wording cited a removed-EOF file at `records == 15`; no fixture on disk reproduces that today, and both `short_eof` fixtures measure `ok? == false` with one error. The conclusion is unchanged, the example is now one that reproduces.) Require an EOF record on top of `ok?` (D23). **Compare the declared record count to the parsed body count plus one** — `EMR_HEADER` counts itself, while `Metafile#records` contains only the records that follow it; the handler enforces this invariant both after a successful parse and through an independent structural count when parsing fails. Map `errors` (message, offset, record_code) to `severity: "error"`, `code: "EMF_PARSE"`, `location: {byte_offset: offset}` — `byte_length` stays nil unless the pre-pass computes it. On severity generally: png_conform emits a SYMBOL (`:error`, measured), `Models::Issue::SEVERITIES` is `%w[error warning info]`, and "map as-is" is safe because lutaml coerces — `Issue.new(severity: :error)` stores the String `"error"` and round-trips, while `:nonsense` is still refused with `Lutaml::Model::ValidationError`. The enum guards either way; the coercion is what makes the symbol harmless, and it is worth knowing rather than rediscovering. Truncation raises **`IOError`** at some cut points and `Emf::FormatError` at others — both belong on the conform allowlist, or a corrupt file exits 4 instead of 1. Swept 2026-09-08 across all **364** cut points of `valid.emf`: `IOError` 96, `Emf::FormatError` 88, `EOFError` 16, no exception at 164. **`EOFError` is a subclass of `IOError`**, so rescuing that pair covers every truncation — verified by rescuing exactly the pair and finding nothing escapes. **But the pair is NOT the whole allowlist**: `bad_comment.emf`, already on disk, raises **`NoMethodError`** from inside the gem, which the pair does not catch. **Do not add it to the allowlist**: it is a gem defect, not a corrupt-input signal. In `emf-0.1.0/lib/emf/emr/parser.rb`, `Emr::Parser#extract_emf_plus` guards on the DECLARED `cb_data >= 4` and then ORs together `data.getbyte(0)`, `data.getbyte(1)`, `data.getbyte(2)` and `data.getbyte(3)` without checking the actual bytesize, so each returns nil and the shifts raise. It is called from `Emr::Parser#call`, OUTSIDE the `rescue StandardError` in `#read_record` that would otherwise have reported the same fault as a `ParseError`. Cited by method name rather than by line number, deliberately: this is another gem's source, so any line reference here rots on its next release. Reachable from ordinary corruption, not just this fixture: 40,000 mutated documents produced 4 `NoMethodError` hits, every one in that function. Report it upstream; do not widen the rescue to swallow it. And note the pre-pass is still needed once it is fixed — with a bytesize guard applied, `bad_comment.emf` comes back `ok? == true, errors == []`, because the gem has no way to say "a comment declares more data than it holds" |
+| postscript | **No mapping — EPS/PS conform is unsupported in v1 (D22).** `Postscript.parse` was measured accepting an unmatched `}`, an undefined operator, a missing operand and raw binary; only an unterminated string raised. There is nothing here that answers "does this conform?", so the handler declares no `conform` capability and the registry raises `UnsupportedFormat` → exit 3 |
+| pdfrb `Validator.validate` | Structural, class method taking a `Document`. Measured `[]` on a valid file. **Failure reporting is not uniform** — a catalog-less document raises `Pdfrb::Error`, a `/Pages` reference to a missing object raises `NoMethodError`, and a dangling unrelated reference comes back as an error string. The allowlist must cover the raising cases including `NoMethodError` from this call path specifically, which means wrapping the call rather than allowlisting `NoMethodError` globally. When it returns strings: `severity: "error"`, `code: "PDF_STRUCTURE"`, `message` the string, `location: nil` |
+| pdfrb `Conformance::*` `Violation` | Only via `--profile`. Measured `PdfA.validate(doc, level: :a1b)` → `ValidationResult` whose violations are `Violation{rule_id, message, object, severity, spec_clause}`, e.g. `rule_id="6.1-2", message="PDF/A requires /Catalog/Metadata XMP stream", object="Catalog", severity=:error`. So `code: rule_id`, `message` as-is (it has real prose — no composition needed), severity as-is, `location: {node_path: object}` — note `object` was the string `"Catalog"`, not a path, so treat it as an opaque label. **`PdfA`/`PdfX`/`PdfVT` take `level:`; `PdfUA` does not** — the adapter is per-profile |
+
+- **One `--profile` flag, two formats.** PDF and SVG both have a
+  generic check and a set of named stricter standards, so they share
+  one mechanism rather than inventing two.
+  - PDF: generic `conform` runs `Validator.validate` (structural).
+    `--profile pdf_a --level a1b` reaches `Pdfrb::Conformance::*`.
+    **A profile run must pass structural validation first** — measured
+    on a catalog-less file, most profiles raise a raw `NoMethodError`
+    while `Pdf2AF` returns zero violations and "passes". Never report a
+    profile pass for a document that is not structurally sound.
+    **Claricle validates the level itself**: `PdfA`, `PdfX`, `PdfVT`
+    and `Pades` accept `level:`; `PdfUA`, `Ltv`, `Pdf2AF` and
+    `TaggedPdf` do not. An invalid level is **silently ignored**
+    upstream — `level: :nonsense` returned the same result as
+    `level: :a1b` — so an unrecognised level must be rejected here with
+    `InvocationError`, and passing `--level` to a profile that takes
+    none is equally an error. Enumerate the accepted names and levels
+    in one table; do not pass user input through unchecked.
+  - SVG: generic `conform` runs the **`base`** profile (D21).
+    `--profile metanorma`, `svg_1_2_rfc`, `svg_1_2_rfc_with_rdf`,
+    `no_external_css`, `lucid_fix` reach the stricter sets.
+  - An unknown profile name, or `--profile` on a format with no profile
+    system, is an `InvocationError` → exit 2.
+  - `Report#profile` always records what actually ran, so no result is
+    ambiguous about which standard it was judged against.
+  "Valid PDF" and "valid PDF/A" are different claims, and so are
+  "well-formed SVG" and "SVG that satisfies the RFC colour rules".
+  Neither is silently substituted for the other.
+- **Arlington is delivered by Claricle's document walk.** Released pdfrb
+  exposes `Arlington::Loader`, predicates and definitions — the grammar,
+  not a runner. `Handlers::PdfArlington` supplies the missing walk from
+  the Catalog down and maps required-key, type and enumerated-name
+  findings into Claricle issues (#55). Generic PDF conformance combines
+  those findings with the structural validator; named profiles remain
+  opt-in.
+- **`conform` still means different things per format, so say so.**
+  PNG gets chunk-level validation, SVG the `base` requirement set, EMF
+  a parse plus `ok?`, PDF a structural check. Those are not comparable
+  claims even after D22 removed the worst offender. `Report#profile`
+  and the validator version record what actually ran, and the README
+  states it per format rather than implying uniformity.
+- Module API: `Claricle.conform?(path = nil, pattern: nil,
+  strict: false, profile: nil)` — exactly one of positional path or
+  `pattern:` (`InvocationError` otherwise; the issue's examples use
+  both shapes); `pattern:` is true only if every matched file conforms.
+  `Claricle.conformance_report(path, profile: nil)` → `Models::Report`.
+  `profile:` is accepted for PDF and SVG (D16, D21); on any other
+  format, or with a name that format does not define, it raises
+  `InvocationError`. `Report#profile` records which one ran, so a
+  result is never ambiguous about what it checked.
+- **A batch predicate loses information, so give callers the full
+  result too.** `Claricle.conformance_batch(pattern:)` returns ordered
+  per-file outcomes plus an aggregate status, so Ruby callers can get
+  what the CLI gets. Without it the CLI records per-file failures and
+  keeps going while the Ruby predicate aborts on the first one, and
+  there's no way to reach the complete picture from Ruby. The batch
+  predicate must collect every outcome — no `all?` short-circuiting —
+  and then deterministically raise the highest-severity operational
+  failure, so the same input always fails the same way.
+- **`conform?` is a predicate, so it answers about conformance and
+  raises about everything else.** A nonconformant file returns `false`.
+  An operational failure — unknown format, unsupported format, missing
+  file, delegate crash — raises, and raises out of the batch shape too;
+  it never silently becomes `false`. `pattern:` matching zero files
+  raises `InvocationError` (matching the CLI's exit 2, not a vacuous
+  `true`).
+- **The batch helper** (owned here, reused by 04): a positional
+  argument is a literal path when it names an existing file and a glob
+  otherwise; `--pattern` forces glob interpretation for a filename that
+  legitimately contains glob characters (D19). Expand
+  `Dir.glob(pattern).sort`; zero matches → exit 2; per-file failures
+  don't stop the batch; final exit = highest code.
+- **One envelope type, never a mixed array.** Every slot is a
+  `Models::BatchItem{path, status, exit_code, result, error}` — one
+  homogeneous element type, with `result` holding the `Report` (or in
+  04 the `Conversion`) and `error` holding code and message. A
+  heterogeneous `Array<Report | Failure>` would force consumers to
+  type-switch on a field's presence, and `jq '.[].result.valid'` would
+  return null for an operational failure, indistinguishable from a
+  genuine null. Human output prints one stderr line per failed file.
+  Because 04 needs the same helper with a different success predicate,
+  keep it operation-neutral — something like
+  `Batch.run(argument, classify:, &operation)` returning ordered
+  envelopes plus aggregate status — rather than baking conform's exit
+  0/1 rule into it and forcing 04 to work around it.
+- CLI: `claricle conform FILE... [--pattern GLOB] [--json] [--strict]`;
+  conformance failure returns 1 as an ordinary integer from the runner,
+  never a raised `SystemExit`; `--strict` requires tri-state `yes`
+  (D8). Batch-capable JSON
+  is **always an array**, single result included; a single-file failure
+  must produce the same JSON envelope as a batch one, so CI consumers
+  never get JSON in one case and bare stderr text in the other.
+  Human output prints, per file: the path, the tri-state verdict, and
+  every mapped issue as one line carrying severity, code, message, and
+  the location fields that are populated. A conformant file prints its
+  path and verdict, nothing more.
+- **One stable JSON cardinality**: batch-capable commands always emit
+  an array of `BatchItem`, single result included. Shape can't follow
+  invocation syntax — a filename may legally contain glob characters,
+  and an unquoted glob is expanded by the shell before Claricle sees
+  the argument, so "which form did the user type" isn't knowable. 04's
+  `convert --json` uses the same rule.
+- `capabilities` gains `conform` per handler **in the same commit that
+  implements that handler's `conformance_report`**, alongside the
+  `formats` output spec — so `formats` never claims an operation that
+  isn't working yet, not even between commits inside this item.
+- Fixtures: one valid + one invalid sample per format, sourced from the
+  delegates' canonical corpora (PngSuite, svg_conform fixtures, emf
+  corpus, pdfrb specs).
+
+## Do
+
+Same shape as 02 — command plumbing first, then one handler per commit,
+so no commit declares a capability the CLI can't yet deliver.
+
+1. `Models::BatchItem` + operation-neutral batch helper + module API +
+   `conform` command, with the exit codes reachable now (2 for zero
+   matches, 3 for a format no handler conforms). Extend the exact command
+   inventory with `conform` in the same commit. No capability changes.
+2. Module API argument specs — both call shapes, `InvocationError`
+   cases, and `conformance_batch` collecting every outcome without
+   short-circuiting.
+3. One handler per commit: `conformance_report` TDD against valid and
+   invalid fixtures, the derived `conform` capability, and the `formats`
+   expected-output update, together. Exit codes 0 and 1 get their
+   end-to-end specs with the first handler.
+4. Per-delegate malformed-input allowlist, per operation and stage, so
+   a recognised-but-corrupt file exits 1 rather than 4 — **for the
+   formats that have conform at all**. EPS and PS are excluded by D22:
+   they exit 3 whatever their content, since there is no conformance
+   verdict to give. `Emf::FormatError`
+   raised while conforming a truncated EMF goes **on** that allowlist:
+   the delegate reports it as an exception before any `metafile.errors`
+   result exists, but the user-visible meaning is the same
+   nonconformance that malformed PostScript produces, and the exit code
+   must follow the meaning rather than the delegate's reporting style.
+   Then prove exit 4 with a deliberately faulting handler — an
+   off-allowlist exception — since every recognised-but-corrupt fixture
+   now correctly lands on 1.
+5. `--strict` + tri-state boundary specs (warnings-only file,
+   info-only file).
+6. README section for `conform` (D1), stating per-format what conform
+   actually checks.
+
+## Done when
+
+- [x] `Claricle.conform?` correct for png, svg, emf and pdf, both call
+  shapes; eps/ps raise `UnsupportedFormat` per D22
+  (`spec/claricle/conformance/module_api_spec.rb`, examples
+  `answers true for a real conformant PNG through the positional call`,
+  `answers true for a real conformant PDF through the positional call`,
+  `answers true for a real conformant EMF and a real conformant SVG`,
+  `answers true for an all-conforming mixed-format pattern`, and
+  `raises rather than answering false when EPS or PS is unsupported`).
+- [x] Invalid fixture of each format yields a `Report` with populated,
+  correctly-mapped issues; exit codes verified end-to-end. png, svg, pdf
+  (`spec/claricle/cli_spec.rb`); invalid EMF exits 1 with its
+  `emf.record_framing` error line (`spec/claricle/cli_spec.rb`, example
+  `exits 1 for a nonconformant EMF, with an error line on stdout`; #71).
+- [x] Batch glob over mixed formats returns highest-code exit and a
+  positionally complete JSON array of `BatchItem`, failures included.
+- [x] A single-file failure emits the same JSON envelope as a batch one.
+- [x] Exit code 4 is reached end-to-end. A corrupt-but-recognised fixture
+  exits 1 for png, svg, emf and pdf; eps and ps exit 3 regardless of
+  content (D22). Exit 4 comes from a real faulting handler run through
+  the real executable (`spec/claricle/cli_spec.rb`, example
+  `exits 4 when the handler raises outside its allowlist, and says what`,
+  with `spec/fixtures/faulting_handler/boom.rb`; #63).
+- [x] `formats` now reports conform, and its spec says so.
+- [x] PDF named profiles map all eight planned pdfrb validators; `--level`
+  validates and maps the accepted PDF/A, PDF/X, PDF/VT and PAdES levels,
+  and structural/Arlington validation runs before a named profile.
+- ~~Full Pre-Push Review Chain passed.~~ Superseded: Hassan 2026-10-09 requires TDD, only changed specs, and green GHA; no extra review chain.
+
+## Files
+
+`lib/claricle.rb` (module API), `lib/claricle/handlers/*.rb`,
+`lib/claricle/models/batch_item.rb`, `lib/claricle/cli.rb` + batch
+helper file, `README.adoc`, `spec/claricle/conformance/*_spec.rb`,
+`spec/fixtures/`.

data/TODO.plan/04-convert.md

@@ -0,0 +1,216 @@
+# 04 — Convert: vectory routing, lossiness, README rewrite
+
+Can start: after 03 (reuses its batch helper). D11 (round-trip
+assertions) and D23 (lossiness classification) settled what it asserts.
+
+## Problem
+
+No conversion exists. The issue requires EMF↔SVG, PS/EPS↔SVG and
+SVG→EPS with explicit lossiness — no silent lossy conversions — plus
+the final README describing the real library. All twelve edges between
+svg/emf/eps/ps were measured working, so v1 ships the full matrix.
+
+## Design
+
+- `Models::Conversion` (lutaml-model): `source_path`, `source_format`,
+  `target_format`, `lossiness`, `output_path`, `content` (excluded from
+  JSON serialization). `source_path` is populated whenever the image
+  came from disk, and nil for a content-born one — `Image#convert`
+  works in memory and has no path to report. It is required in every
+  path that batching can reach, since that is where a result must be
+  traceable to its input; never substitute a Tempfile path to fill it.
+- Conversion routes through vectory: `Vectory::Emf.from_content(...)
+  .to_svg` and siblings. All twelve svg/emf/eps/ps edges succeed **on a
+  rect-and-line fixture** (D9) — that is what "the matrix works" means,
+  and no more. Richer content fails in ways the matrix cannot express:
+  gradients raise on SVG→EMF, and the SVG→EPS path raised
+  `NameError: uninitialized constant Postsvg::Model::UnknownOperator`
+  on a cold process for an embedded raster, then succeeded once an
+  unrelated conversion had run first. That load-order bug will present
+  as intermittent, so the spec suite must exercise each edge in a fresh
+  process, not only after other conversions have warmed the constants (done in #70: `spec/claricle/conversion/fresh_process_spec.rb`, one fresh
+  process per convert edge). WMF is out of v1 entirely (D14)
+  and never reaches a handler; png and pdf have no vectory class.
+- **Lossiness is per-conversion, not per-edge (D10 superseded, D23).**
+  Measured: SVG→EPS silently turns a gradient solid black, silently
+  removes a clip path, and silently deletes an embedded raster, while
+  the same edge is perfectly clean for a rect. SVG→EMF *raises* on a
+  gradient (`Emfsvg::FormatError: unsupported SVG color`) but silently
+  makes a clipped object invisible. A static per-edge label would
+  therefore call SVG→EPS lossless on rect evidence and then destroy a
+  gradient without a word — the exact silent lossy conversion issue #1
+  forbids. So: inspect the source document for the features known to be
+  dropped on that edge, and classify **this** conversion. The
+  `:lossless` / `:lossy` / `:unknown` vocabulary stands; the static
+  table becomes a pessimistic floor, never the answer. Build the
+  feature list from the fixture corpus and grow it as more losses are
+  found. Human output discloses lossy/unknown conversions through its
+  warning or batch summary; JSON output carries the classification in
+  the result and deliberately keeps stderr clean. No consent-gate flag
+  — the issue requires disclosure, not consent.
+- **Write lifecycle**: `Image#convert(to:)` never touches disk.
+  `Claricle.convert(src, to:, output: nil, force: false)` writes to the
+  given path; stdout for `"-"`; with `output: nil` derives the sibling
+  path (source name, target extension — the issue's
+  `convert("diagram.emf", to: :svg)` writes `diagram.svg`).
+  `Conversion#output_path` = actual written path, nil for
+  stdout/in-memory.
+- **Same-format conversion is an invocation error, not a crash.**
+  `Vectory::Svg#to_svg` does not exist — every same-format pair raises
+  `NoMethodError`, which would exit 4 as an internal fault. Reject
+  `--to` equal to the detected source format up front with
+  `InvocationError` → exit 2, before any delegate is touched.
+- **A successful `from_content` proves nothing about the content.**
+  Measured: EPS bytes into `Vectory::Emf`, EMF bytes into
+  `Vectory::Eps` and raw SVG into `Vectory::Emf` all construct without
+  complaint and only fail at the conversion call. Detection remains the
+  only authority on what a file is; never infer it from a delegate
+  accepting the bytes.
+- **One overwrite rule, both layers**: an existing destination is never
+  overwritten without `force: true`/`--force`, and it makes no
+  difference whether the path was derived or given explicitly. Refusing
+  raises `InvocationError` at API level and exits 2 at CLI level. Two
+  rules here would be a trap — the derived path is the one the user
+  didn't type and so the one they're least likely to be watching.
+- **Batch conversion must preflight the whole write set before writing
+  anything.** Derived sibling names plus batching plus `--force` is a
+  data-loss machine otherwise. Real cases: `a.emf` and `a.svg` in one
+  run targeting SVG, where converting the EMF overwrites a later input;
+  `a.eps` and `a.ps` both deriving `a.svg`, where one result destroys
+  the other; `Logo.eps` and `logo.ps` colliding on a case-insensitive
+  filesystem; and `convert logo.svg --to emf --output logo.svg --force`
+  destroying its own source. So: resolve every source/destination pair
+  up front, compare by **filesystem identity** rather than string
+  equality (symlinks, hardlinks, case folding), reject any destination
+  that is also a source, and reject non-unique destinations even under
+  `--force`. Note a **nonexistent** destination has no inode to compare
+  — `Logo.svg` and `logo.svg` collide on a case-insensitive filesystem
+  before either exists. So canonicalize planned destinations by probing
+  the target directory's case sensitivity once, and compare
+  canonicalized strings for paths that do not yet exist. A preflight
+  collision **fails the whole batch before any write**, rather than
+  producing per-item failures — half-written output is worse than none,
+  and the user can fix the input set and re-run. `--force` authorises replacing an unrelated existing file,
+  never clobbering an input.
+- **Writes are atomic in both directions.** Without `--force`, stage to
+  a temp file in the destination's own directory and publish with a
+  no-replace atomic operation, so a concurrent writer can't slip
+  between the existence check and the write. With `--force`, stage the
+  same way and atomically rename over the target, so a serialization or
+  disk failure can't truncate a good existing file. For `--output -`,
+  generate the bytes fully before writing and use binary
+  `stdout.write` — never `puts`, which appends a newline and corrupts
+  binary output. Spec it byte-for-byte.
+- CLI: `claricle convert SOURCE... [--pattern GLOB] [--to FORMAT]
+  [--output FILE|-] [--json] [--force]` — same invocation shape as
+  `conform` (D19): a positional source is a literal path when it names
+  an existing file and a glob otherwise, with `--pattern` forcing glob
+  interpretation. Batch runs via 03's helper, every file landing in a
+  uniform `Models::BatchItem` slot, failures included. `--output` names
+  a single destination, so it is rejected with exit 2 whenever more
+  than one source resolves; multi-source runs use derived names. `--to` may be omitted **only** when
+  `--output` names a file whose extension maps to a known format; that
+  extension then decides the target. Omitting both, or giving an
+  extension that maps to nothing, exits 2 with a message naming the
+  problem — there is no default target and no guessing from the source
+  format, drawn from the handlers' declared canonical extensions rather
+  than a central table. `--to svg --output result.emf` is a conflict,
+  not a preference — exit 2 rather than silently letting one win.
+  `--output -` puts bytes alone on stdout, and rejects `--json` and a
+  missing `--to` (exit 2, since there's no extension to infer from).
+  Everything else — the human summary, lossiness warnings, error text —
+  goes to stderr in that mode, so the stdout stream stays pipe-safe.
+  `--json` serializes `Conversion` minus content, always as an array of
+  `BatchItem` per 03's rule. Human output prints one line per file:
+  source, target format, written path (or `-`), and the lossiness
+  classification.
+- `capabilities` gains `convert` plus that handler's target list in the
+  same commit that implements the edge (per 00's rule), with the
+  `formats` output spec moving alongside. The last such commit is what
+  finally makes `claricle formats` the full support matrix the issue
+  asks for.
+- **There is no general round-trip invariant, and that is measured
+  (D11).** Byte identity against the original never held — the first
+  pass always rewrites. Idempotence held for a rect-and-line fixture
+  across the measured routes. With a single `<text>` element, the EMF
+  chain also stabilises after the first rewrite, but the EPS chain does
+  not: its viewBox grows `0 0 100 50` → `0 0 100 90` →
+  `0 0 100 180`, and its text y coordinate moves `-40` → `-90` →
+  `-180`. So do **not** write a general `cycle N == cycle N+1` spec:
+  one stable route does not establish the property across the supported
+  matrix.
+  What can honestly be asserted: conversion is **deterministic** (same
+  input, identical bytes — measured true); same-format parse→serialize
+  identity for EMF; and per-feature semantic properties over a fixture
+  corpus, each naming the property it checks. These are D11's replacement
+  for the issue's stated general backbone.
+  Also note "dimension preservation" is not assertable until D15
+  settles units — the same SVG reports `3×1` through vectory and
+  `96×48` as EPS, so an equality check would be testing a coincidence.
+- Docs closure: README.adoc fully rewritten on top of 01's honesty
+  baseline — real API + CLI, the format × operation matrix, exit codes,
+  and the registry extension workflow. That workflow must describe what
+  adding a format **actually** costs: if handlers do not yet implement
+  their operations or declare sniffers, targets, extensions and lossiness,
+  then it is a handler class plus a detector edit plus a require plus a
+  registry entry plus a lossiness edge, and the README says so rather
+  than repeating the one-class claim. Gemspec description refreshed for
+  the operations that now exist; its URLs moved to the `claricle` org in
+  01 and need no further edit. `sig/` stays deleted (01's docs rule).
+  Extend the exact command inventory with `convert` in the same commit
+  as the command.
+
+## Do
+
+Plumbing first again, then one edge family per commit.
+
+1. `Models::Conversion` + the per-target feature-loss rules (D23) +
+   specs. Not a flat edge table — a rule says "this target discards
+   gradients / clip paths / embedded rasters", and the classifier
+   inspects the source for those features.
+2. Extract the write lifecycle as its own injectable service and spec
+   it directly — preflight collision set, filesystem-identity aliasing,
+   no-replace atomic create, force-mode temp-and-rename, binary stdout.
+   01 freezes the registry and bans runtime mutation and test-only
+   APIs, so there is no honest route from a detected real format to a
+   stand-in handler; testing the service directly avoids needing one.
+3. `convert` command + batch + `--force`/`--output -`/`--json`
+   boundary specs + `--to` inference, its exit-2 cases, and the
+   `--to`/`--output` suffix conflict; `--output -` spec asserts stdout
+   carries bytes only, with no trailing newline. Extend the exact command
+   inventory with `convert` in the same commit.
+4. One edge family per commit: handler `convert` TDD against real
+   fixtures, override `convert`, declare only that handler's target-list
+   data, and update the `formats` expected output together.
+5. Semantic spec suite over the fixture corpus, each spec naming the
+   property it checks (D11 rejects a general invariant, so do not
+   write a general round-trip assertion). Add a feature-loss rule only
+   when a fixture demonstrates the loss.
+6. `formats` full-matrix spec once the last edge lands.
+7. README rewrite + gemspec metadata.
+
+## Done when
+
+- [x] All acceptance-matrix conversions work via API and CLI with correct
+  exit codes and output-mode-appropriate lossiness disclosure.
+- [x] Semantic suite green; every `:lossless` classification is
+  fixture-proven for the features present in that fixture, and the
+  gradient, clip-path and embedded-raster cases each produce a
+  `:lossy` classification disclosed in human or JSON output rather than
+  silent loss.
+- [x] A batch that would collide or overwrite an input is refused before
+  anything is written, and specs cover the four concrete cases.
+- [x] `claricle formats` prints the complete support matrix — every cell
+  matches what actually works.
+- [x] README describes only verified behavior; issue #1 acceptance
+  checklist fully satisfiable, or the gaps are signed off (D11, D14, D18, D22).
+- ~~Full Pre-Push Review Chain passed.~~ Superseded: Hassan 2026-10-09 requires TDD, only changed specs, and green GHA; no extra review chain.
+
+## Files
+
+`lib/claricle/models/conversion.rb`, `lib/claricle/handlers/
+{metafile,postscript,svg}.rb`, `lib/claricle/writer.rb` (write
+lifecycle service), `lib/claricle/registry.rb`, `lib/claricle.rb`,
+`lib/claricle/cli.rb`, `README.adoc`, `claricle.gemspec`,
+`spec/claricle/conversion/*_spec.rb`, `spec/claricle/writer_spec.rb`,
+`spec/claricle/cli_spec.rb`.

data/exe/claricle

@@ -3,4 +3,4 @@
 
 require "claricle"
 
-Claricle::Cli.start(ARGV)
+exit Claricle::Cli::Runner.run(ARGV)