Repository source: docs/plans/human_readable_formats_checklist.md

Human-readable format audit

Policy: CONTRIBUTING. Canonical records and human-facing files use Key: value headers and readable text bodies. JSON inside a header is still JSON; changing the extension alone is not a fix.

Source audit: 2026-10-25, baseline 2a07313a738af9e0a0f15796e8155d301d949ed5. Includes repository records, source routes, exports, operator configuration, reports, CLI output, and browser templates. This is a static source inventory, not runtime verification or a claim that every diagnostic path was exercised. Priorities below identify follow-up work. Retraction replacement (F01/R04), shared removal receipts (F02) and approval acceptance receipts (F03) and agent-response metadata (F05) are complete; the remaining conversions are not authorized by this checklist.

Historical source review: 2026-10-27, baseline 085c47701f57334164f7fe1c562454443cd65596. At that review, 2 of 16 audit items were complete and 14 remained open: 11 confirmed conversions (F02–F12) and 3 boundary checks (R01–R03). This review rechecked the listed format producers and boundary evidence; it is not a fresh exhaustive inventory or runtime verification.

2026-10-29 conversion checkpoint: 3 complete (F01/F02/R04), 13 open (10 conversions F03–F12 and 3 boundary checks R01–R03). F02 verification and F01 shared-format integration are recorded in the implementation summary.

2026-10-29 F03 closeout: 4 complete (F01/F02/F03/R04), 12 open (9 conversions F04–F12 and 3 boundary checks R01–R03). F03 retains legacy compatibility with an explicit conversion and future-reader-removal path; earlier counts remain historical. Verification.

Latest listed-producer review: 2026-10-29, baseline 9005e87611b82e2304c0be52505d994674dc4efa (main). F03 is merged and pushed in 9005e876, with 33 post-merge checks passing. At that planning checkpoint, status was 4 complete / 12 open. Current status: 5 complete / 11 open after approved F05 implementation; 8 conversions (F04, F06–F12) and 3 boundary checks (R01–R03) remain. Verification and limits. This review rechecked the listed remaining producers and boundary evidence, not every runtime path or a fresh exhaustive inventory.

Prioritization rubric

Priority score = 2 × consequence + exposure + friction (0–12; higher first). Scores are source-based judgments, not measured usage or effort estimates. Canonical readability gets extra weight because it is a platform contract.

Factor	0	1	2	3
Consequence	Internal protocol only / human role unconfirmed	Informational or diagnostic	Setup, moderation, import decisions or recovery	Durable canonical fact or signed public record
Exposure	Human access unconfirmed	Exceptional recovery or fallback	Deliberate source/archive/document inspection	Normal human command output or manual input
Friction	No demonstrated JSON burden	Simple scalar fields or list	Structured values mixed into text/output	Nested records or escaped multiline evidence

Each item shows its score and C/E/F inputs so the ranking is reviewable. Within each section, work highest score first; ties use the existing item ID. IDs stay stable and are not ranks. Scores prioritize value, not implementation sequence: F01 and its companion R04 were completed together. Among the remaining canonical conversions, F05 is now highest priority; this ranking does not select or approve a new implementation cycle. Boundary-check scores prioritize investigation only, not an unconfirmed conversion; do not combine their queue with confirmed rewrites. Re-score when actual user evidence or a clarified human-facing contract changes an input.

Completed guidance

Record the rule in CONTRIBUTING.md and make it discoverable in AGENTS.md.
Identify format consumers and separate human-facing conversions from machine data.
Record the maintainer's retraction scope: ignore previous retractions; no migration or backward-compatibility work. This exception does not automatically apply to other record families.
Record the separate 2026-10-27 maintainer decision for F02: abandon existing JSON source/label removal records; no migration or backward-compatible reader is required for their replacement. The project is young and not meaningfully in use. This exception is specific to F02 and does not extend to other record families or backups. It records the compatibility decision, not implementation or physical file deletion.
Record the 2026-10-29 unified-format scope revision: the maintainer confirms there is no existing data to save and authorizes abandonment of previous F01 text receipts as well as F02 JSON records. The unified-format cycle needs no legacy readers, migration, historical replay or old pending-state recovery. New-format signing, authorization and retry correctness remain required. No data deletion or implementation is performed by this decision; other families and backups are unaffected.

Canonical records — convert

F01 · Priority 11/12 (C/E/F 3/2/3) — Retraction acceptance. Replaced JSON with a signed text request, detached signature and separate text acceptance receipt. Preserved new-request signing, actor/author attribution, structure, deletion/retry, rebuild, import protection and cleanup. Evidence: AcceptedRetraction (source unavailable), source paths (source unavailable), import planner (source unavailable), sweep (source unavailable). Current assessment. Existing retractions need not be converted or supported. The subsequent shared-format cycle replaces the original F01 receipt codec for new records.
F02 · Priority 11/12 (C/E/F 3/2/3) — Source/label removal acceptance. Replaced JSON with records/post-removals/*.txt, sharing the readable receipt codec and interpretation with signed F01 retractions. Retains source/label hashes, conversation structure and distinct local/signed authority; compatible same-post bindings combine without losing signed evidence. Previous F01 text receipts and F02 JSON are unsupported, with no migration or old-state recovery. Evidence: shared contract, LabelRemoval (source unavailable), verification and limitations.
F03 · Priority 11/12 (C/E/F 3/2/3) — Approval acceptance receipts. New receipts use named text fields at records/approval-acceptances/*.txt, preserving grant bytes and historical signed context digests. Existing JSON evidence remains readable through an isolated adapter; explicit preview/conversion/retry and readiness commands preserve authority, restore and acceptance facts. The removal guide separates legacy file decoding from retained digest verification and requires an old-archive decision. Evidence: receipt specification, implementation and verification. No production conversion or legacy-reader retirement performed.
F04 · Priority 9/12 (C/E/F 3/2/1) — Legacy timestamp companions. records/post-timestamps/*.json contains three scalar fields. Replace with text headers and retain the exact original-record hash binding. Evidence: LegacyPostTimestamp (source unavailable), post specification.
F05 · Priority 10/12 (C/E/F 3/2/2) — Agent response metadata inside posts. New signed replies use named headers. Old signed records remain byte-identical through an isolated legacy decoder; mixed-generation expansion, rebuild, transfer and offline relationships are preserved. Read-only readiness lists legacy dependencies and scan blockers, with history/archives explicitly unknown. New-format flows pass with the adapter unavailable. Machine read-model/offline JSON stays unchanged. Evidence: format specification, removal guide, implementation and verification. No production conversion, deployment or actual reader removal.

Human-facing configuration, exports and output — convert

F06 · Priority 8/12 (C/E/F 2/3/1) — Import source aliases. import-instance --sources requires a manually supplied JSON name-to-URL map. Use readable key/value configuration and update examples/errors. Evidence: InstanceSourceResolver (source unavailable), CLI (source unavailable).
F07 · Priority 6/12 (C/E/F 2/1/1) — Fastmod rubric selection/recovery. state/private/fastmod_rubrics.json is normally UI-managed, but recovery explicitly asks operators to edit a JSON array. Use a readable ordered selection format or remove manual JSON recovery through an equivalent supported control. Evidence: FastmodSelection (source unavailable), operator recovery.
F08 · Priority 10/12 (C/E/F 2/3/3) — Import review report. The CLI directs operators to report.json. Produce a human-readable review report; keep the private resumable import journal separate. Evidence: CLI (source unavailable), ContentImportRunner (source unavailable).
F09 · Priority 9/12 (C/E/F 2/2/3) — Backup/archive inventories. Thread archives contain manifest.json; image backups contain manifest.json and paired repository backups contain repository-snapshot.json. Convert project-owned inventories into readable records, retaining all file/hash/pairing checks and restore behavior. Evidence: archive-thread (source unavailable), ImageBackup (source unavailable), RepositorySnapshot (source unavailable). Restore compatibility needs its own decision; the retraction exception does not authorize discarding backups.
F10 · Priority 9/12 (C/E/F 2/3/2) — Image restore/verify output. ./v3 images verify|restore prints JSON unconditionally. Provide readable default results and an explicit machine-output option. Evidence: restore_images.php (source unavailable).
F11 · Priority 9/12 (C/E/F 2/3/2) — Fast-score and worker output. Meta commands, retry/invalidate and inspect output include unconditional JSON; progress includes JSON scores/signals. Use named values or readable lists by default, with explicit JSON for automation. Evidence: fast_score.php (source unavailable), task_queue.php (source unavailable).
F12 · Priority 7/12 (C/E/F 2/1/2) — Nested values in other human CLI output. Non-JSON delete-record and high-traffic branches still serialize arrays as JSON; provider-test and agent-status formatting also falls back to JSON. Replace those human display fallbacks while preserving explicit machine modes. Evidence: delete_record.php (source unavailable), high_traffic.php (source unavailable), agent_reply_status.php (source unavailable), test_agent_reply_provider.php (source unavailable).

Boundary checks — resolve before assigning a conversion

R01 · Priority 5/12 (C/E/F 1/1/2) — LLM exchange viewer. Human prompt/response views already exist, but structured fallbacks and errors display JSON. Improve those displays; determine whether explicitly labeled raw request/response disclosures should remain exact protocol diagnostics. Do not rewrite provider payloads merely to change their presentation. Evidence: llm_exchange.php (source unavailable).
R02 · Priority 2/12 (C/E/F 0/0/2) — Signed operational payloads. Offline intents embed Payload: {…}; Fastmod/high-traffic preparation signs JSON. Determine whether these are inspectable human records or exclusively internal request protocols, then convert human records with signing verification. Evidence: outbox_intent.js (source unavailable), LocalWriteService (source unavailable). No confirmed human preview is claimed by this source audit.
R03 · Priority 7/12 (C/E/F 2/1/2) — Checkout recovery. The CLI guide tells operators to inspect <id>.result.json; registry/preview/result files are otherwise managed internal state. Provide a readable recovery inspection path if direct JSON inspection is required; do not convert all registry/cache files by default. Evidence: CheckoutManager (source unavailable), CLI guide.
R04 · Priority 5/12 (C/E/F 1/2/1) — Retraction attribution documentation. Reconciled the schema spec with the text receipt and removed the internal JSON-trailer round trip and historical acceptance reconstruction. No legacy-record migration. Evidence: LocalWriteService (source unavailable), read-model spec.

Machine data reviewed — retain unless its human-facing contract changes

JSON API/LLM transport, explicit --json, SQLite JSON columns, browser storage, prepared-write/recovery journals, caches, offline/PWA/search manifests and query catalogs are machine interfaces or state. Encrypted key/history envelope JSON is an internal serialization, not the readable outer backup format. QDB import JSONL is an intermediate pipeline format. Dependency manifests, third-party datasets, test fixtures and frozen study evidence are not canonical platform record formats. Do not rewrite exact protocol diagnostics or frozen evidence to satisfy this audit.

Compatibility simplification recommendations — 2026-10-27

Recorded at the maintainer's request. These recommendations guide future scoped planning; they do not approve implementation, deletion of existing data, or blanket abandonment of other formats. F02's explicit compatibility exception above remains separate. No additional audit item is complete and priority scores are unchanged.

Items	Recommended approach	Conditions and retained requirements
F06 — Import source aliases	Require manual recreation in the new readable configuration format; avoid an automatic migration or legacy reader.	Update examples and errors so operators can recreate their mappings.
F07 — Fastmod rubric selections	Prefer recreation through the supported UI over migrating the old JSON selection file.	Confirm loss of the current selection is acceptable; preserve ordering and a usable recovery path.
F08 — Import review reports	Emit the readable report for future runs; leave old reports as historical artifacts.	Keep private resumable import journals separate and preserve resume behavior. No retrospective report conversion is recommended.
F10–F12 — CLI output	Change future human-facing output directly; no stored-record migration is needed.	Preserve existing explicit machine modes and provide explicit JSON output where needed for automation.
F03 — Approval acceptance receipts	Consider abandoning old receipts only if the associated identities/grants can also be discarded or re-established.	Decide explicitly whether existing account/key approval evidence must survive; preserve signed grant/context bindings for retained records.
F04 — Legacy timestamp companions	Consider abandoning old companions only if their dependent posts can be discarded or reimported with valid timestamp evidence.	Removing companions while retaining dependent legacy posts can break loading. Establish disposability or a reimport path first.
F05 — Agent response metadata	Consider supporting only new headers if old agent replies and their dependent relationships can be discarded or regenerated.	Do not rewrite historical signed replies in place; preserve attribution and version relationships for retained records.
F09 — Backup/archive inventories	Make old-archive support a separate decision; no abandonment recommendation yet.	Dropping old formats gives up restoration from affected archives. F01/F02 exceptions do not authorize this.

Current clarification: F03 chose preservation and explicit conversion, superseding its abandonment suggestion above. F05 chose preserved signed records and isolated legacy reading; its abandonment suggestion is also superseded. F04 still requires a decision about underlying records before treating their JSON metadata as disposable. R01–R03 remain boundary investigations; this recommendation does not turn their internal state or signed protocols into conversion targets.

Closing each conversion

Apply these checks separately to each conversion and link its verification from the corresponding item above. These reusable checks are not additional open audit items; F01/R04 completion evidence is in their implementation summary.

Specify fields, repeated values and multiline content under docs/specs/ for canonical formats; include a readable example and malformed-input behavior.
Verify actual writers, readers, source/download routes, import/export and recovery; preserve signed bytes and trust boundaries. Explicitly decide compatibility for that family.
Update affected tests/docs and inspect the human result. UI changes follow CONTRIBUTING.md; record evidence here or link their implementation summary.

Initial audit verification: source references and Markdown local links checked; no runtime formats changed at that audit checkpoint. F01/R04 implementation and verification are recorded in the implementation summary. F02 subsequently closed through the shared-format cycle and F03 through the approval receipt cycle. F05 later closed as recorded below; F04 and F06–F12 remain open.

— Codex · 2026-10-25 UTC

Initial prioritization verification (before F01/R04 completion): all 16 then-open audit items scored; component ranges and weighted totals checked. Existing IDs, evidence, completion states and conversion boundaries preserved. Documentation only; no new Railspike cycle or runtime tests.

— Revised by Codex · 2026-10-25 UTC

2026-10-27 review

Confirmed F01's retained request/signature/text-receipt implementation in AcceptedRetraction; F01/R04 verification remains linked to the existing implementation summary. No implementation tests were rerun for this review.
Rechecked F02–F12 against the listed record codecs, writers, configuration reader, export inventories and CLI output. Their JSON formats remain present; no additional conversion is marked complete and scores are unchanged.
Rechecked R01's viewer fallbacks, R02's signed payload serialization and R03's documented direct result-file inspection. Their boundary questions remain open; source inspection alone does not establish a human-facing contract for R02.
Corrected the planning-only introduction and distinguished the original scoring checkpoint from current completion counts. Clarified per-conversion closeout and existing signed-record handling for F05.
Verification: local Markdown link targets, item counts, priority arithmetic and diff whitespace checked. Documentation only; no runtime/UI verification, new Railspike cycle or dependency changes.

— Reviewed by Codex · 2026-10-27

2026-10-29 shared-format closeout

F02 and F01 integration are implemented locally, with new signed and local receipts using one readable format. No previous records are converted or supported. CLI/API/browser, source/archive, rebuild/import, label-only resolution and new-action recovery checks are recorded in the linked implementation summary. No production data deletion, deployment or history purge; zero dependency delta. Other item scores and the earlier static-review checkpoint remain historical and unchanged.

— Codex · 2026-10-29 UTC

2026-10-29 approval receipt closeout

F03 is complete locally. Text-only writes, validated legacy conversion/retry, source/history, full/incremental rebuild, trusted archive restore and independent reader-retirement checks passed. Signed context hashing remains unchanged and separate from legacy storage decoding. Production conversion, actual reader removal, old-backup abandonment and deployment are not performed. Other format families remain outside this cycle. See the linked implementation summary for commands, browser evidence and limitations.

— Codex · 2026-10-29 UTC

2026-10-29 post-merge review and F05 intake

F03 merge/push confirmed at 9005e876; post-merge receipt, approval-history, signed-finalization, private-source and Railspike checks passed 33/33. Existing F03 verification remains linked above; no production conversion or deployment.
Rechecked F04–F12's listed JSON producers and R01–R03's viewer/protocol/recovery evidence. They remain open with unchanged scores; boundary checks remain investigations rather than approved rewrites. F01/F02/R04 completion evidence is carried forward, not reverified in this planning turn.
F05's shared writer emits the embedded header; its parser supplies normalized metadata to full/incremental read models and offline snapshots. Initial scripture replies and expansions share source/version bindings. The proposed new-header path preserves these machine interfaces and existing signed bytes.
Linked the new Step 1 assessment, clarified F03's superseded compatibility suggestion, and retained historical counts/verification. Counts, priority arithmetic, local file links and whitespace checked. No runtime tests were rerun for this documentation-only review; no implementation, dependency, todo.txt, commit or publication changes.

— Codex · 2026-10-29 UTC

F05 Step 1 revision: The maintainer requested eventual legacy-reader removal to be designed in. Compatibility remains recommended now; the assessment includes isolated decoding, readiness/dependency inspection and current-format verification without the adapter. Actual removal must resolve retained signed posts and old archives explicitly. F05 remains open; counts and scores are unchanged.

— Codex · 2026-10-29 UTC

F05 progress: Revised Option A received Step 1 approval; Step 2 is drafted. Legacy compatibility remains required, with retirement readiness and a separate later removal decision. F05 remains open; 4 complete / 12 open.

F05 progress: Step 2 approved; five-stage development plan drafted for Step 3 review. Implementation remains unapproved. Counts remain 4 complete / 12 open.

2026-10-29 F05 implementation closeout

Approved Steps 1–3 executed in five stages on feature/agent-response-text. New signed records use readable headers; retained old records and signatures are not rewritten. Readiness and decoder-unavailable acceptance establish a bounded future removal path, with archive policy and actual retirement still separate decisions.

Verification: 90 focused PHP checks plus four readiness checks after final review (all passing; overlapping coverage), and Chromium thread/post, raw source and offline checks at 375/1280 pixels. Actual PHP request/fulfillment/import flows use deterministic providers; browser API responses are intercepted. No full suite, live provider, physical device or deployment claim. Zero dependencies/schema delta. See the implementation summary.

Current count: 5 complete / 11 open. Next canonical conversion: F04, legacy timestamp companions; it needs its own planning/approval cycle.

— Codex · 2026-10-29 UTC