shuttlecheck 0.1.0__tar.gz

shuttlecheck-0.1.0/LICENSE

@@ -0,0 +1,43 @@
+ShuttleCheck — Licence
+Copyright (c) 2026 MVRK Systems. All rights reserved.
+
+This software is made available free of charge. It is not open source.
+
+PERMITTED
+
+  You may install this software and use it, without charge, for any purpose
+  including commercial work, on any number of machines, for as long as you
+  like. No account, licence key or registration is required.
+
+  You may run it against any material you are lawfully in possession of, and
+  you may share the reports it produces with anyone.
+
+NOT PERMITTED
+
+  You may not redistribute this software, in whole or in part, in original or
+  modified form, whether or not for a fee.
+
+  You may not modify, adapt, translate, reverse engineer, decompile or create
+  derivative works from it, except to the extent that this restriction is
+  prohibited by applicable law.
+
+  You may not remove or alter this notice, or any attribution contained in the
+  software.
+
+  You may not sublicense, rent, lease or sell it, or offer it as a hosted or
+  managed service.
+
+NO WARRANTY
+
+  This software is provided "as is", without warranty of any kind, express or
+  implied, including but not limited to the warranties of merchantability,
+  fitness for a particular purpose and non-infringement.
+
+  In no event shall MVRK Systems be liable for any claim, damages or other
+  liability, whether in an action of contract, tort or otherwise, arising from,
+  out of or in connection with the software or its use.
+
+  This software reports on files. It does not modify them. You remain
+  responsible for verifying your own deliverables.
+
+Questions, and licences permitting anything above: hello@mvrk.systems

shuttlecheck-0.1.0/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: shuttlecheck
+Version: 0.1.0
+Summary: Check media filenames, folder structure and deliverables against a written convention. Read-only.
+Author-email: MVRK Systems <hello@mvrk.systems>
+License: Proprietary — free to use, no redistribution
+Project-URL: Homepage, https://mvrk.systems/shuttlecheck
+Project-URL: Documentation, https://mvrk.systems/shuttlecheck#checks
+Keywords: broadcast,post-production,dailies,media,naming-convention,file-naming,delivery,conformance,validation,vfx,video
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: Other/Proprietary License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: System :: Archiving
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: jsonschema>=4.20
+Requires-Dist: tzdata>=2024.1; sys_platform == "win32"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Dynamic: license-file
+
+# ShuttleCheck
+
+**Check media filenames, folder structure and deliverables against a written
+convention.** Nothing in this package renames, moves or deletes anything.
+
+On a production the naming convention is a PDF or a message in a chat, and
+every vendor on the job breaks it. Nobody finds out until a conform fails in
+post, or a lab rejects a delivery at four in the morning.
+
+```bash
+pip install shuttlecheck
+shuttlecheck ui
+```
+
+Point it at a job you have already finished. It works out the convention you
+are already using, then shows you every file that does not follow it.
+
+---
+
+## It reads the convention off your own files
+
+Nobody can describe their naming convention in the abstract, and nobody should
+have to. Point `init` at a finished job and it recovers the fields, tells you
+how confident it is in each one, and flags anything it had to guess at.
+
+```
+FIELDS RECOVERED
+  {project}      constant   100%  NRD24
+  {day}          integer     90%  DAY1, DAY2
+  {stage}        enum        80%  HALLA, HALLB
+  {session}      integer     90%  SES001, SES002
+  {title}        slug        85%  opening-remarks, keynote
+```
+
+It handles conventions that disagree with themselves — several accepted forms
+per field, optional elements, free-text titles containing the separator —
+because real ones do.
+
+## Then it tells you what breaks it
+
+```
+SHUTTLECHECK CONFORMANCE REPORT
+  files scanned      412
+  conforming         398
+  errors               9   ingest will fail
+  warnings             5   inconsistent, will work
+
+ERROR    filename-mismatch   (6)
+  D02/MAIN/MASTERS/AUT26_D02_MAINSTAGE_S114_v01.mov
+    the stage field does not match what the spec allows
+```
+
+Findings name the field at fault, not just the file. Errors mean an ingest will
+reject it; warnings mean it is inconsistent but will work. The two are never
+conflated, because a noisy report does not get read.
+
+## What it checks
+
+| | |
+|---|---|
+| Names and folders | Against a pattern, with the offending field identified |
+| Codec and container | Read from the file, not from the filename's claim |
+| Resolution, frame rate, scan | Including 29.97 handled as `30000/1001` |
+| Audio | Channel count, layout, sample rate, bit depth |
+| Sidecars | Captions, checksums, metadata a deliverable must carry |
+| Packages | Whether a session is short a master, a proxy, a cutdown |
+| Portability | Illegal characters, reserved names, path length, case collisions |
+| Unicode | Names that compare equal on one platform and not another |
+
+Media inspection uses `ffprobe` when it is on your PATH. When it is not, those
+checks are reported as **skipped** — never as passed. A silent skip is how a
+conformance tool starts lying.
+
+## For live events, the running order does the work
+
+An event agenda is structured data that exists weeks before anyone turns a
+camera on. Joined against time-of-day timecode, every recording names itself —
+stage, session, speaker, sponsor — with no inference of any kind.
+
+It will also tell you when a filename is well-formed and still wrong: `S007`
+recorded during `S011` is a valid shape carrying a false claim, and only the
+running order knows.
+
+## Checking a drive that arrived
+
+If a drive was sealed with a convention on it, one command with no arguments
+checks both that it arrived intact and that the names conform:
+
+```bash
+shuttlecheck verify /Volumes/SHUTTLE01
+```
+
+No spec to be told about, no account, no connection.
+
+---
+
+## What this package will not do
+
+It will not rename, move or delete anything. That boundary is the point: it is
+the command a stranger will run on a live job, because running it cannot cost
+them anything.
+
+Conforming files, the reversible journal, sealing drives and per-vendor specs
+are licensed separately as ShuttleCheck Pro. Asking for one of those commands
+here prints an explanation rather than an error.
+
+## Licence
+
+Free to install and use. Not open source: no right to redistribute or modify.
+See <https://mvrk.systems/shuttlecheck>.
+
+Made by [MVRK Systems](https://mvrk.systems).

shuttlecheck-0.1.0/PYPI.md

@@ -0,0 +1,112 @@
+# ShuttleCheck
+
+**Check media filenames, folder structure and deliverables against a written
+convention.** Nothing in this package renames, moves or deletes anything.
+
+On a production the naming convention is a PDF or a message in a chat, and
+every vendor on the job breaks it. Nobody finds out until a conform fails in
+post, or a lab rejects a delivery at four in the morning.
+
+```bash
+pip install shuttlecheck
+shuttlecheck ui
+```
+
+Point it at a job you have already finished. It works out the convention you
+are already using, then shows you every file that does not follow it.
+
+---
+
+## It reads the convention off your own files
+
+Nobody can describe their naming convention in the abstract, and nobody should
+have to. Point `init` at a finished job and it recovers the fields, tells you
+how confident it is in each one, and flags anything it had to guess at.
+
+```
+FIELDS RECOVERED
+  {project}      constant   100%  NRD24
+  {day}          integer     90%  DAY1, DAY2
+  {stage}        enum        80%  HALLA, HALLB
+  {session}      integer     90%  SES001, SES002
+  {title}        slug        85%  opening-remarks, keynote
+```
+
+It handles conventions that disagree with themselves — several accepted forms
+per field, optional elements, free-text titles containing the separator —
+because real ones do.
+
+## Then it tells you what breaks it
+
+```
+SHUTTLECHECK CONFORMANCE REPORT
+  files scanned      412
+  conforming         398
+  errors               9   ingest will fail
+  warnings             5   inconsistent, will work
+
+ERROR    filename-mismatch   (6)
+  D02/MAIN/MASTERS/AUT26_D02_MAINSTAGE_S114_v01.mov
+    the stage field does not match what the spec allows
+```
+
+Findings name the field at fault, not just the file. Errors mean an ingest will
+reject it; warnings mean it is inconsistent but will work. The two are never
+conflated, because a noisy report does not get read.
+
+## What it checks
+
+| | |
+|---|---|
+| Names and folders | Against a pattern, with the offending field identified |
+| Codec and container | Read from the file, not from the filename's claim |
+| Resolution, frame rate, scan | Including 29.97 handled as `30000/1001` |
+| Audio | Channel count, layout, sample rate, bit depth |
+| Sidecars | Captions, checksums, metadata a deliverable must carry |
+| Packages | Whether a session is short a master, a proxy, a cutdown |
+| Portability | Illegal characters, reserved names, path length, case collisions |
+| Unicode | Names that compare equal on one platform and not another |
+
+Media inspection uses `ffprobe` when it is on your PATH. When it is not, those
+checks are reported as **skipped** — never as passed. A silent skip is how a
+conformance tool starts lying.
+
+## For live events, the running order does the work
+
+An event agenda is structured data that exists weeks before anyone turns a
+camera on. Joined against time-of-day timecode, every recording names itself —
+stage, session, speaker, sponsor — with no inference of any kind.
+
+It will also tell you when a filename is well-formed and still wrong: `S007`
+recorded during `S011` is a valid shape carrying a false claim, and only the
+running order knows.
+
+## Checking a drive that arrived
+
+If a drive was sealed with a convention on it, one command with no arguments
+checks both that it arrived intact and that the names conform:
+
+```bash
+shuttlecheck verify /Volumes/SHUTTLE01
+```
+
+No spec to be told about, no account, no connection.
+
+---
+
+## What this package will not do
+
+It will not rename, move or delete anything. That boundary is the point: it is
+the command a stranger will run on a live job, because running it cannot cost
+them anything.
+
+Conforming files, the reversible journal, sealing drives and per-vendor specs
+are licensed separately as ShuttleCheck Pro. Asking for one of those commands
+here prints an explanation rather than an error.
+
+## Licence
+
+Free to install and use. Not open source: no right to redistribute or modify.
+See <https://mvrk.systems/shuttlecheck>.
+
+Made by [MVRK Systems](https://mvrk.systems).

shuttlecheck-0.1.0/README.md

@@ -0,0 +1,392 @@
+# ShuttleCheck — validator
+
+Naming conformance for a folder tree: infer a spec from it, check it, fix it,
+undo the fix, and send the convention with the media. Installs as `shuttlecheck`;
+the Python package is `shuttlecheck`.
+
+`init`, `validate`, `verify` and `conform` (without `--apply`) never write to
+the tree; `seal` writes only inside `_SPEC/`. Only `conform --apply` and
+`revert --apply` move media, and both are journalled with a working undo. The
+validator staying read-only is the point: it is the command a stranger can be
+talked into running on a live job, because running it cannot cost them anything.
+
+## Install
+
+```bash
+python -m pip install -e .
+```
+
+`tzdata` is a real runtime dependency on Windows — the platform ships no system
+timezone database, so `zoneinfo` cannot resolve the agenda timezone without it.
+
+## Use
+
+The app is the front door:
+
+```bash
+shuttlecheck ui
+```
+
+That serves a page from the package itself, opens a browser at it, and walks
+you through pointing at a folder, reading the convention off it, seeing what
+does not conform, and fixing what can be derived. No network is used at any
+point. `shuttlecheck ui /Volumes/LAST_JOB` opens straight onto a folder.
+
+Everything the app does is also a command, which is what you want in a cron
+job or a delivery hook. Start by reading the convention off a job that already
+exists:
+
+```bash
+shuttlecheck init /Volumes/LAST_JOB
+```
+
+That infers the spec, validates the tree against what it inferred, prints both,
+asks only about what it could not settle, and writes `_SPEC/spec.yaml`. Add
+`--yes` to skip the questions, `--project-code` to override the detected code,
+`--vocabulary film` for a shoot rather than an event.
+
+Then check any tree against it:
+
+```bash
+shuttlecheck validate /Volumes/SHUTTLE01 --spec EXC26/_SPEC/spec.yaml
+```
+
+```bash
+shuttlecheck validate /Volumes/SHUTTLE01 --spec spec.yaml --json --out report.json
+```
+
+```bash
+shuttlecheck check-spec --spec examples/event-conference.yaml
+```
+
+Seal the drive before it ships, and verify it when one arrives:
+
+```bash
+shuttlecheck seal   /Volumes/SHUTTLE01 --spec spec.yaml --hash
+shuttlecheck verify /Volumes/SHUTTLE01                          # no --spec needed
+```
+
+Fix what can be fixed:
+
+```bash
+shuttlecheck conform /Volumes/SHUTTLE01 --spec spec.yaml            # plan only
+shuttlecheck conform /Volumes/SHUTTLE01 --spec spec.yaml --apply    # execute
+shuttlecheck history /Volumes/SHUTTLE01
+shuttlecheck revert  /Volumes/SHUTTLE01 --apply                     # undo the last run
+```
+
+Exit codes: `0` clean, `1` findings at error level (or any level with
+`--strict`), `2` the spec or the path could not be read.
+
+## What it checks
+
+| Rule | Level | What it means |
+|---|---|---|
+| `filename-mismatch` | error | Name does not parse against the context's pattern |
+| `folder-mismatch` | error | File is not in the folder its context requires |
+| `token-conflict` | error | The same token disagrees between folder and filename |
+| `schedule-mismatch` | error | Named session is not the session the agenda had running |
+| `forbidden-char`, `reserved-name`, `trailing-char` | error | Will not survive a Windows ingest |
+| `path-too-long`, `filename-too-long` | error | Over the platform limit |
+| `case-collision` | error | Siblings differ only by case |
+| `unscheduled-media` | warning | No session was running at that clock time |
+| `loose-file`, `missing-folder` | warning | Structure does not match the spec |
+| `unicode-normalisation` | warning | NFD name; compares unequal across platforms |
+| `unclassified` | info | No context matched; the file was not checked |
+| `spec-*` | error/warning | Problems in the spec itself, not the tree |
+
+Delivery rules, for contexts that declare a `deliverable:` profile:
+
+| Rule | Level | What it means |
+|---|---|---|
+| `container-mismatch` | error | Wrapper is not what the spec asks for |
+| `codec-mismatch` | error | Wrong codec or ProRes/DNx variant |
+| `resolution-mismatch`, `framerate-mismatch`, `scan-mismatch` | error | Wrong picture |
+| `video-bitdepth-mismatch` | error | 8-bit where the spec says 10 |
+| `audio-channels-mismatch`, `audio-samplerate-mismatch`, `audio-bitdepth-mismatch`, `audio-track-count-mismatch`, `audio-layout-mismatch` | error | Wrong sound |
+| `duration-out-of-range` | error | Too short or too long |
+| `timecode-missing`, `timecode-start-mismatch` | error | Start timecode wrong or absent |
+| `missing-sidecar` | error | Captions or checksum did not arrive with the file |
+| `no-video-stream`, `no-audio-stream`, `unreadable-media` | error | Not the kind of file it claims to be |
+| `color-*-mismatch` | error | Tagged with the wrong colour space |
+| `color-*-unknown` | warning | Not tagged at all — absence is not proof of wrongness |
+| `incomplete-package` | error | A session or episode is short a deliverable |
+| `spec-unknown-deliverable` | error | A context points at a profile that is not defined |
+
+Severities are overridable per rule in the spec's `rules:` block.
+
+## The app
+
+`shuttlecheck ui` is a local web UI, not Electron and not Qt. The page ships
+inside the wheel and is served by the standard library's HTTP server, so the
+install stays `pip install shuttlecheck`, nothing is downloaded at runtime, and
+it works with no connection at all — which matters, because the machine this
+runs on is often in a truck. No web fonts either; the stylesheet falls back to
+whatever the OS has.
+
+Two safety properties are worth knowing, because a local server that renames
+files is a different proposition from one that serves a blog:
+
+**Every API call carries a session token.** Any page open in any tab can issue
+requests to `127.0.0.1`. Without a token, a site you happened to visit could
+drive a tool that renames your media. The token is minted at startup, travels
+in the URL the browser is opened with, and never leaves the machine.
+
+**Applying a plan requires echoing back the move count.** The page states how
+many moves it believes it is approving. If the folder changed since the plan
+was drawn, the numbers disagree and nothing runs — a stale tab cannot apply a
+plan that no longer matches reality.
+
+## How inference works
+
+`init` reads the tree rather than asking you to describe it, because nobody can
+describe their own convention in the abstract and most people should not have
+to try.
+
+1. **Group** files by the nearest role folder above them (`MASTERS`, `ISO`,
+   `PROXY`, `DELIVERABLES`, ...) and by media kind.
+2. **Split** each group's filenames on the separator that divides them most
+   consistently. Where a free-text title contains that separator and every file
+   has a different field count, anchor from the left and the right while the
+   columns still look like fixed codes and treat the remainder as one variable
+   field. Names structurally unrelated to the rest are set aside first, and
+   reported — they are usually the existing violations.
+3. **Profile** each column: constant, prefixed counter, enum, date, slug, or
+   free text, each with a confidence and a plain-English reason.
+4. **Reconcile** value sets across groups, so a column that reads as the
+   constant `HALLA` in one group and the enum `{HALLA, HALLB}` in another
+   becomes one token rather than two.
+5. **Name** the fields from prefix semantics rather than exact widths — `D01`
+   and `DAY1` are both `{day}` — falling back to `{field3}` and flagging it.
+6. **Self-validate**: run the validator over the same tree with the spec just
+   inferred, and show the result. That is the thirty-second demonstration.
+
+Constants other than the project code become literals in the pattern, so you
+get `{project}-{day}-{stage}-{session}-proxy` rather than a token bound to the
+constant `proxy`.
+
+Everything is conservative on purpose. A spec that over-constrains flags every
+file and gets deleted; one that under-constrains still finds the real outliers
+and can be tightened by hand. Low-confidence guesses are listed in the header
+comments of the file it writes.
+
+## How the conformer works
+
+It renames only what it can *derive*. For each non-conforming file:
+
+1. Parse the folder and the filename against the context's patterns.
+2. If both parse but disagree on a token, **skip** — there is no safe way to
+   tell which one is the mistake, so it is a question for a human.
+3. If the name fails on a single field, recover that one field: from the folder
+   path, by matching a known alias, by re-applying the token's own transforms
+   (which fixes casing, spaces and punctuation), or from its declared source.
+4. If a context sets `schedule_check`, cross-check the schedule-bound tokens
+   against the agenda and correct them. A name can parse perfectly and still be
+   wrong — `S001` recorded during `S005` is a valid shape carrying a false
+   claim. An ambiguous clock window corrects nothing rather than guessing.
+5. If the correct name still cannot be derived, **skip and say why**. Inventing
+   a session number is worse than leaving a bad filename.
+
+Safety, none of it optional:
+
+| | |
+|---|---|
+| Dry run | The default. `--apply` is a separate, explicit act. |
+| Originals | `rename: never` contexts are never planned, moved, or renamed. |
+| Overwrite | Never. A destination that exists aborts the whole plan. |
+| Collisions | Two files resolving to one name abort everything — a half-renamed job is worse than an unrenamed one. |
+| Stale plans | Every source is re-checked for size and mtime before the first move. |
+| Case-only renames | Routed through a temporary name, as are swaps and cycles. |
+| Mid-run failure | Every completed move is rolled back, and the run is marked `rolled_back` in the journal. |
+
+## The delivery spec
+
+Naming is the wedge; this is the business. A file can be named perfectly and
+still be rejected at ingest for being 8-bit instead of 10, 29.97 instead of 25,
+six audio channels where the spec says two, or arriving without its captions.
+
+`deliverables:` profiles say what a file must *be*; a context points at one with
+`deliverable:`. `packages:` says what a session or episode owes in total, which
+is the only way to catch the master that was never exported at all.
+
+Three things worth knowing:
+
+**Frame rates compare with a tolerance.** A spec says `29.97`, a file says
+`30000/1001`. Exact comparison fails every NTSC delivery ever made.
+
+**MOV and MP4 cannot be told apart by `format_name`.** They share an ffprobe
+demuxer and both report `mov,mp4,m4a,3gp,3g2,mj2`, so taking the first entry
+marks every MP4 as a MOV and fails every MP4 delivery. The ftyp major brand is
+the real discriminator, with the file extension as a fallback.
+
+**Without a media inspector, every media check reports as skipped.** Not passed.
+The report prints a `SOURCES NOT AVAILABLE` block naming exactly what was not
+checked. A delivery report that silently checked nothing is worse than no report
+at all.
+
+`ffprobe` is the default inspector and is found on PATH. `Prober` is the seam if
+you ever want a different one.
+
+## Vendor packs
+
+A convention only works if everyone on the job follows the same one, and a job
+has a captions vendor, a social edit shop and a sponsor agency, none of whom
+share a network with the production or with each other.
+
+```bash
+shuttlecheck pack    /Volumes/JOB --spec spec.yaml --vendor captions
+shuttlecheck vendors /Volumes/JOB --spec spec.yaml
+```
+
+`pack` writes a folder holding a scoped `spec.yaml`, anything it references,
+and a README that states the obligation in plain words:
+
+```
+WHAT YOU ARE DELIVERING
+  Speaker copy
+    folder    {project}/DELIVERABLES/SPEAKERS/{day}
+    filename  {project}_{day}_{session}_{speaker}_{title}_{version}
+    must be   container mp4, codec h264, resolution 1920x1080 or 1280x720,
+              25 fps, 2 audio channel(s)
+    with      Subtitles ({stem}.srt)
+```
+
+The pack is **derived**, never authored separately — a vendor cannot drift from
+a document they did not write. `vendors` is the other direction: point it at the
+incoming deliveries and it reports who is clear, who has errors, and who has
+sent nothing at all.
+
+Two things worth knowing:
+
+**Out-of-scope contexts are kept as inert stubs, not deleted.** Contexts are
+first-match-wins, so removing an early one silently re-routes its files into a
+later catch-all — the ISO rushes would come back reported as malformed masters.
+The stubs preserve ordering and say plainly: not yours.
+
+**A vendor is never shown a rule they cannot act on.** Packages narrow to the
+requirements they own; a package that ends up empty is dropped rather than
+shown as trivially satisfied. Noise is what stops a report being read.
+
+## The journal
+
+`_SPEC/journal/`, one append-only JSON Lines file per run, flushed after each
+move so an interrupted run records what actually happened rather than what was
+intended.
+
+Its second job matters more than undo. Every file carries an `original_path`,
+recorded the first time it is touched and never rewritten. When a spec is
+edited and the tree re-conformed, names are computed from that identity — never
+from the current name. Without it, tokens compound on every pass: the second
+run re-prefixes what the first already prefixed, and by the third edit the
+names are unrecoverable. That failure is silent and looks like it worked.
+
+## The drive sidecar
+
+A convention is only worth anything if everyone downstream uses the same one,
+and downstream is a different company on a different network reading a shuttle
+drive out of a Peli case. `seal` writes `_SPEC/` onto the drive itself:
+
+| File | What it is |
+|---|---|
+| `spec.yaml` | the convention, plus every file it references (the agenda travels too) |
+| `manifest.jsonl` | one JSON object per line: path, size, mtime, optional hash |
+| `REPORT.txt` | the conformance report as it stood when the drive was sealed |
+| `README.txt` | plain-language instructions for someone who has never heard of this tool |
+| `journal/` | what has been renamed, and by which spec revision |
+
+The receiving end runs `shuttlecheck verify .` — no spec to be told about, no
+account, no connectivity. Sealing never touches the media; it only writes
+inside `_SPEC/`.
+
+What `verify` reports:
+
+| | |
+|---|---|
+| `missing` | error — on the manifest, not on the drive; the copy is incomplete |
+| `size-mismatch` | error — damaged or replaced in transit |
+| `hash-mismatch` | error — same size, different contents (needs `--hash` at both ends) |
+| `added` | warning — on the drive but not the manifest |
+| `mtime-drift` | info — most copy tools do not preserve timestamps |
+| `clock-did-not-survive-copy` | warning — see below |
+
+Two judgement calls worth knowing about.
+
+**Timestamp drift is not damage.** Most copy tools do not preserve mtime, so
+treating that as corruption would make every genuine transfer look broken.
+*But* if the spec joins the agenda on `file_mtime`, drift silently moves every
+recording to the wrong session and the naming findings become fiction — so that
+specific combination is raised as a warning rather than left to be discovered.
+A spec using embedded timecode does not have the problem.
+
+**Hashing is opt-in.** Re-hashing terabytes to restate what an existing MHL
+already asserts wastes hours, so where checksum sidecars are already on the
+drive they are noted and left to do their job. Without `--hash`, sizes and
+timestamps are all that can be checked, and the sidecar says so in writing.
+
+## Design notes
+
+**It parses, it does not render.** The validator compiles each naming pattern
+into a regex whose groups are constrained by each token's own type, enum values,
+and transforms, then matches the existing name against it. That is why it needs
+no prompting, no schedule, and no media parser to do its core job — and why
+`prompt`-sourced tokens validate fine.
+
+**Mismatches name the field.** On a failure it recompiles the pattern with each
+token loosened in turn; whichever loosening makes the name match is the field at
+fault. "The stage field does not match what the spec allows" is a finding
+someone fixes. "Does not match the pattern" is a finding someone ignores.
+
+**Missing sources are reported as skipped, never as passed.** Timecode and
+embedded start times need a media parser. Without `ffprobe` on PATH the report
+prints a `SOURCES NOT AVAILABLE` block naming what could not be checked. A
+silent skip is how a conformance tool starts lying.
+
+**Original recorder output is never name-checked.** Contexts declaring
+`rename: never` have their folder structure validated and their filenames left
+alone, and the schema will not let such a context propose a name at all.
+
+## Tests
+
+```bash
+python -m pytest -q
+```
+
+213 tests, across three fixture trees.
+
+`tests/make_fixture.py` writes seven conforming files and six deliberate
+violations, plus an agenda whose slots are stamped onto file mtimes so the
+schedule join is exercisable without a media parser:
+
+```bash
+python -m tests.make_fixture ./fixture
+shuttlecheck validate ./fixture --spec ./fixture/EXC26/_SPEC/spec.yaml
+```
+
+`tests/make_infer_fixture.py` writes a tree using a convention the code has
+never seen — dashes instead of underscores, `DAY1` instead of `D01`, `SES001`
+instead of `S001`, variable-length titles containing the separator, and
+camera-native ISO names. If inference recovers that, it is reading the tree
+rather than recognising something baked into the source:
+
+```bash
+python -m tests.make_infer_fixture ./infer-fixture
+shuttlecheck init ./infer-fixture --yes
+```
+
+The load-bearing test is the round trip: infer a spec from a tree, then run the
+validator over that same tree with that spec, and assert it finds no naming
+errors in the files it learned from.
+
+Portability rules are unit-tested against the check functions rather than real
+files, because Windows cannot create a file named `NUL.mov`, `bad<name>.mov`, or
+`trailing..mov.` — which is the point of the check.
+
+## Not built yet
+
+- Embedded metadata tokens beyond a start time (reel, camera ID, lens, BWF
+  scene/take). `MediaProbe` is the seam; it currently reads timecode and
+  creation time via `ffprobe` and degrades honestly without it.
+- Agenda formats other than CSV. `ics`, `sched`, `swapcard`, and `cvent` are in
+  the schema and raise `ScheduleUnavailable` rather than failing the run.
+- The conformer, its journal, and revert. Deliberately absent — see the
+  read-only boundary above.