Turn Document Contents into a Complete File-Naming Packet

A useful content-based naming job ends with files you can identify, a complete old-to-new mapping, and evidence for every field in each approved name. Start by reading the documents. Keep uncertain fields visible, approve a specific mapping, then check the actual files after applying it to a disposable copy.

This tutorial supplies eight complete, original workshop notes as UTF-8 text. Four can be named from their contents. Four need review and remain under their original names. The finished renamed copy contains all eight, with their original content bytes intact. The readable preview connects every source ID to its proposed name, approved decision and actual result.

The fixtures contain no people, customers, financial records or real business documents. Their fields were checked by the author. No separate model-extraction experiment was performed; the bad suggestions below are authored examples, not captured AI mistakes. The file operations and checks were actually run locally.

Get the inputs and keep identity separate from the name

Download the source packet, input inventory, field evidence and naming rules. The complete kit list and run instructions link every required file, including the two small Python programs. Keep the packet files together in a new local folder.

Each note has a stable Source-ID. The inventory binds that ID to its original basename, byte count and SHA-256. A row number or directory listing order is not the identity. Nor does matching subject text prove two files are duplicates.

For example, Scan001.txt contains this complete note:

Document-Type: workshop-note
Source-ID: F01
Document-Date: 2026-04-03
Project: amber
Subject: airflow
Revision: a

Fictional teaching material. No people, customers or financial records.
Check the paper vane at the practice vent.

IMG005.txt, ID F05, has the same date, project, subject and revision, but its last line describes a wider paper vane. It has different bytes and a different hash. Both notes belong in the output; this is naming, not deduplication.

The full selection is:

All eight are the same document type and retain .txt. The dates are fictional document fields, not execution times or filesystem timestamps.

Record the field evidence before proposing names

The 48-row evidence table covers six fields for every file: document type, source ID, document date, project, subject and revision. Each row records the raw value, source line numbers, exact field excerpt, status, adopted value and author decision.

For F01, the date is explicitly labelled on line 3. For F03, no Document-Date line exists. That absence has no invented line number. F04 has two date lines, 3 and 4; neither is adopted. F08 supplies one slash-form date but gives no date order. Choosing April 5 or May 4 would add a fact the document does not establish.

F06's subject field is blank, and the note says it is unreadable in the fictional transcription. Writing “notes” would disguise the missing subject rather than recover it. Its approved-name cell stays empty.

For another collection, a person might supply a missing value from an authoritative source. That would need its own recorded evidence and a newly reviewed plan. This packet does not repair unknown document facts by looking at today's date, the original filename or file creation time.

If you ask an AI assistant to suggest fields, make it return the source ID, field value, location and uncertainty before it proposes a filename. Then compare those claims with the actual document. Here the author supplied that baseline directly; no extraction accuracy or time saving was measured.

Use one complete naming rule and a separate approval column

The approved rule is:

<document-date>__<project>__<subject>__rev-<revision>__<source-id-lowercase>.txt

Dates must be single, unambiguous calendar dates in YYYY-MM-DD. Project, subject and revision must be verified lowercase ASCII tokens using letters, digits and internal single hyphens. Names are basenames only, at most 160 ASCII bytes, with .txt preserved. There is no automatic transliteration, suffix allocation or truncation.

For F01 this gives 2026-04-03__amber__airflow__rev-a__f01.txt. F05 gets the same content fields followed by f05, so it remains distinguishable without guessing a new subject or discarding a document.

The complete rename plan keeps proposed_name, approved_name, status and reason separate. It includes all eight IDs, original paths and hashes, plus references into the evidence table. Only an approved row with its exact canonical name may execute. Blank approved cells are intentional holds, not an invitation for the helper to complete the name.

Read the wrong proposal and its repair

The complete wrong plan deliberately leaves IDs out of the names. That sends F01 and F05 to the same target. It also inserts an unsupported 2026-10-22 into F03's missing date, picks F04's first conflicting date, invents “notes” for F06's subject and uses F08's ambiguous slash date.

These are author-created errors chosen to make the review visible. They are not evidence about how often a model or user makes them. The preview shows every wrong name beside its repaired decision.

The repair has two parts. Add each verified stable ID to otherwise valid names. Keep the four uncertain documents unchanged. The result is four approved names and four blocked rows, rather than eight superficially complete guesses.

You can inspect both plans without touching any files:

python3 rename_packet.py preview --plan wrong-plan.csv
python3 rename_packet.py preview --plan rename-plan.csv

The recorded wrong-plan run also attempted evaluation in a disposable source copy. Every row was rejected and every source file remained unchanged. Duplicate targets are checked across the complete selection, so changing row order cannot select an arbitrary winner.

Apply only inside a new teaching directory

The helper requires macOS. The recorded final run used Python 3.9.6 on macOS 26.5.2 arm64, on an APFS volume; a local probe observed case-insensitive lookup. This is one tested runtime and filesystem, not a portability result. The code uses only Python's standard library and a Darwin system call; it downloads no packages.

Use a new, unused /private/tmp/fw1-... name. The initialization command refuses an existing directory, even an empty one. It extracts only the eight known archive entries into a private files directory and records the directory identity. Subsequent operations require that marker and identity. No folder is discovered by scanning the desktop or home directory.

python3 rename_packet.py init /private/tmp/fw1-reader-one
python3 rename_packet.py apply /private/tmp/fw1-reader-one
python3 rename_packet.py apply /private/tmp/fw1-reader-one

The first apply should report F01, F02, F05 and F07 as applied; the other four remain blocked. The repeated command should report the four completed rows as already_applied, after checking the journal and current bytes. It is not a second set of renames. Confirmed completion is matched separately by the packet, source ID, original name, source bytes/hash and exact original-to-target operation, plus the current file checks. A semantically identical CSV with an extra trailing blank line can therefore identify the same completed operation; a different target is not accepted as that operation.

Inspect each returned row. Command exit 0 means the evaluation returned normally; it does not mean every row was approved or changed. An invalid invocation exits 2. Do not identify success from the command's exit alone.

The helper checks the expected source bytes before a rename, then checks that the old name is absent and the new file has the expected bytes afterward. A journal intent is flushed before the operation and the result is recorded afterward. A missing result stays unknown and prevents automatic replay. That guard follows the stable source ID within the packet-bound owned directory, across every plan hash and before evaluating a replacement proposal. Saving the same CSV again or proposing a different target cannot clear the uncertainty. The raw plan hash remains in the audit record, but is not the unknown-history boundary.

For the actual filesystem operation, the helper calls renameatx_np with RENAME_EXCL and RENAME_NOFOLLOW_ANY, relative to the open teaching directory. Apple's rename manual source specifies refusal when an existing destination conflicts with the exclusive flag, on supported filesystems. Apple's header defines the flags. The helper has no replacing fallback if the operation is unsupported.

An existence check followed by ordinary Unix rename would be insufficient: Python's OS documentation explains that an existing file destination may be replaced. Here the exclusive primitive itself was tested against an occupied target and returned EEXIST, preserving both files. That test supports this local behavior; it is not a cross-filesystem guarantee.

Keep this exercise private, without concurrent external writers. The pre-operation content check is not an atomic lock against another program editing the source. The journal is not a batch transaction or a crash-recovery service. If you need shared-directory coordination, arbitrary formats or production recovery, this narrow helper is not that implementation.

Check the complete output, then review reversal separately

The actual renamed-copy.zip was captured from final-run copy A after its forward operations and before reversal. It contains exactly:

2026-04-03__amber__airflow__rev-a__f01.txt
2026-04-04__cobalt__latch-fit__rev-b__f02.txt
Scan003.txt
Scan004.txt
2026-04-03__amber__airflow__rev-a__f05.txt
Scan006.txt
2026-04-08__elm__hinge__rev-c__f07.txt
Scan008.txt

The applied results record every ID in both final-run copies, its original and actual name, outcome, bytes and hash. Every file matches its source bytes. Copy B was freshly extracted from the frozen source archive; it did not receive A's generated files. These are two author executions, not independent review.

The reversal plan includes only the four confirmed forward operations. It is a reviewable map, not an unconditional Undo promise. To request reversal in the teaching directory, use its journal:

python3 rename_packet.py reverse /private/tmp/fw1-reader-one

The helper rechecks the current renamed file and refuses an occupied original name. In the ordinary A and B exercises, all four names were restored with matching bytes. In a separate exercise, a later teaching file occupied Scan001.txt. F01's reversal was blocked, that later file survived, and only F02, F05 and F07 were restored. Both F01's renamed file and the later original-name occupant remained. Calling that branch “fully undone” would be wrong.

The general design questions are developed in Specify What Undo Restores and Explain a Partly Successful Batch Before Repeating It. This packet adds the concrete document inputs, evidence-to-name mapping and actual file output.

Reproduce the recorded exercise and understand its limits

With the complete kit in one folder, run:

python3 reproduce.py

It creates new private teaching roots, records actual commands, exits and output, checks both fresh copies and the edge cases, captures the renamed ZIP and result tables, then removes only the roots it created. It writes the generated evidence files beside the script, so run it in your own copy of the kit if you want to retain the supplied recorded evidence unchanged.

The final recorded exercise contains 38 helper commands and ten case groups. execution.json retains the commands and returned rows; conflicts.csv collects the observed blocked or unknown rows. The cases include existing and duplicate targets, changed or missing sources, invalid extensions and outside paths, the complete wrong plan, a later reversal conflict, and a direct occupied-target system-call check. Missing, conflicting, ambiguous and unreadable fields are exercised by the main source selection.

The last group inserts an explicitly authored pending journal intent and verifies that the helper refuses replay with unknown. Calls with an authored unknown-result record also stay unknown instead of replaying. For both a pending intent and an unknown result, the recorded exercise checks the original plan, a byte-different CSV with exactly equal parsed rows, and a plan with F01’s target changed. Each keeps F01 unknown, all eight files unchanged and the following seven IDs unprocessed. The variant refusals also leave the existing journal bytes unchanged. A reverse request under the changed plan is refused as unknown too. It does not simulate power loss or establish crash durability. Unknown stops further rows; the remaining IDs are reported as unprocessed. An ordinary blocked row can coexist with other successful rows, so the batch is intentionally not atomic.

The complete request captures the work-product scope. The author verified the final run's per-file results and source archive hash; all twelve final-run disposable roots were removed. Publication and independent editorial acceptance are separate steps.

Choose the amount of automation the documents justify

Limited public questions about multi-file content naming and an office-document workflow motivated this task. The saved research records individual self-reports, not a representative customer sample or a current product defect. A counterexample discussion prefers predictable rules and previews. None establishes an AI accuracy or throughput advantage. Collision and reversal checks in this packet are editorial acceptance choices.

For a small collection, manual field review and naming may be enough. For known prefix, suffix or counter rules, ordinary batch tools may be more appropriate. An assistant becomes a candidate when understanding the document actually matters, and its suggestions still need evidence and review. You can type or dictate the request; verify IDs, dates, paths and negation in any transcript. The input method does not establish a better file result.

The deliverable to judge is the complete packet: every source document, every field decision, every approved or blocked mapping, and every resulting file. A neat list of suggested names is only one intermediate step.