AI-Native Catalogue Enrichment Service

The project began with three documents and no repository: a ~900-line specification (27 sections covering objective, boundaries, architecture, schema, scoring weights, thresholds, a retry matrix, 11 work packages and acceptance criteria), ~390 lines of engineering rules, and ~380 lines of agent operating rules with authentication invariants and a security review checklist. Two properties of that input mattered more than its length. It stated invariants, not just features — "a missed match is recoverable; a wrong artwork assignment silently corrupts the catalogue" decided a dozen later arguments without anyone re-litigating them. And it pre-empted a specific wrong turn by name, correcting upfront the plausible misconception that one identity provider could authorise calls to a different provider's API.

The split was not evenly distributed across the work — and that is the point. Human attention concentrated where it was worth most: domain facts the model could not know (which database, which table, which column), product judgement with no technically correct answer (when one recording appears on an album, a single and three compilations, which cover art is "right" is a taste decision about a catalogue, not an engineering one), and authorisation of anything irreversible — no write reached the production catalogue without explicit, scoped approval. Everything else — architecture, schema shape, concurrency strategy, error taxonomy, test design — was drafted by the model and reviewed rather than directed.

The ledger classifies the human's sixteen: four domain facts the model could not know, six product judgements with no technically correct answer, six authorisations of irreversible actions. The model's twenty-five span architecture, schema design under the real engine's constraints, and ten safety decisions — from structurally unobtainable tokens to single-statement paired writes.

The specification survived, but not unamended. Six changes came from the client correcting the brief — the instructive one being the datastore. The spec named PostgreSQL; the real catalogue was MySQL 5.7, which parses CHECK constraints and silently ignores them. A schema written to the specification would have carried constraints that enforced nothing, and nobody would have known. The fix expressed those vocabularies as ENUM, with tests proving the database itself rejects a bad value. When a specification and reality disagree about infrastructure, the risk is rarely the obvious incompatibility — it is the silent one.

The larger category of change could only be learned by running against real data. The provider's own search is not exact — a query naming a song's specific version returned zero results while the same query without it returned nine, so the service relaxes its search while keeping its judgement strict. Region selection was corrected by measurement, not reasoning, after the plausible choice silently deleted a fifth of the coverage. And the first live run invalidated a core assumption: the winner-margin rule, designed to flag genuine ambiguity, fired on 6 of 10 songs because the same recording legitimately appears on an album, a single and a compilation with identical scores — extrapolated across ~85,000 songs, it would have flooded a review queue no human would ever clear. The rule wasn't wrong; its scope was. A rule that is correct on ten hand-written examples can still be unusable at catalogue scale.

The acceptance bar lives in files, not conversations. A 29-case labelled fixture covers exact matches, Unicode, punctuation, multi-artist credits, live, remix, remaster, cover, karaoke, duplicate titles and no-match — with precision as the gate: zero incorrect automatic matches permitted, because a missed match is recoverable and a wrong one is not. Threshold changes require fixture evidence, not argument. Authoritative schema tests run against a pinned MySQL 5.7 container because that is where the silent-CHECK behaviour lives; concurrency is asserted, not assumed — twelve threads racing for one work item produce exactly one winner, forty items across eight workers partition with zero overlap. 41% of the Java written is test code. That ratio was not a target; it is what proving these properties actually cost.