Repository modernization

This document tracks the controlled reorganization of the MMA Matlock repository.

Current status

Stage 4 of 10 — Writer frontend module split: COMPLETE

Next stage: Stage 5 — Development-script organization

Stages 0–3 established the repository and media contracts. Stage 4 replaces the Writer’s monolithic source-of-truth with maintainable source modules while preserving the same public /assets/writer.js runtime interface.

Rollback point

The repository state immediately before modernization is preserved at:

Stage 0 baseline

Measurements from the rollback commit:

Large runtime-data files include:

These are observations, not cleanup targets by themselves.

Safety rules for every stage

  1. Existing public URLs are preserved unless a stage explicitly documents a redirect or retirement.
  2. Existing article media is not relocated merely to make old folders look cleaner.
  3. A file is not moved or removed until the reference audit has been run against it.
  4. Generated files are treated separately from authored source files.
  5. Writer storage behavior changes only in a Writer-specific stage with Writer regression tests.
  6. Every stage must pass repository integrity, Jekyll/site checks, and feature-specific tests it touches.
  7. Structural cleanup is performed in small reversible changes rather than one repository-wide rewrite.

Reference audit

Stage 0 added a repository-aware reference audit that is now part of Site Quality CI.

Run the full inventory/report locally with:

npm run audit:repo

Before changing a specific tracked path, inspect inbound references with:

npm run audit:repo -- --target news-v3.html
npm run audit:repo -- --target assets/some-file.js

Machine-readable output is available with:

npm run audit:repo -- --json

CI runs:

npm run audit:repo -- --check

The check currently protects against duplicate root permalinks and root pages referencing missing page_styles or page_scripts assets. The report also inventories repository responsibilities and identifies legacy/versioned page candidates with inbound references.

Critical production surfaces

Public routes that later stages must continue to protect:

Content invariants:

Automation that must remain operational includes site quality/build checks, Writer production smoke tests, Writer backend quality tests, scheduled publishing, news updates, On This Day generation, Matchmaker generation/validation, and event-data jobs.

Stage 1 organization contract

Stage 1 formalized the stability-first repository model in two forms:

The contract establishes:

The policy is checked in CI with:

npm run check:repo-policy

That check verifies the permanent roots, Jekyll permalink contract, protected paths, media separation, GitHub Release video policy, and staged legacy exceptions before later migrations build on top of them.

Stage 2 article media hierarchy

Stage 2 routes new Writer image uploads into article-owned directories:

assets/uploads/articles/YYYY/MM/article-slug/

The Writer derives the year and month from the article date and uses the saved filename slug when available, falling back to the article title slug for an unsaved article. Existing files under assets/uploads/ are not moved or renamed.

The Writer upload UI and backend allow nested article-media paths, and production smoke coverage verifies that new uploads resolve under the article hierarchy. GitHub Release video uploads remain unchanged and outside Git history.

Stage 2 also made the repository-policy stage validator reusable for later stages. Site Quality, Writer auth quality, Writer production smoke, and GitHub Pages deployment all passed before Stage 2 was closed.

Stage 3 media pipeline separation

Stage 3 formalized three independent media lanes:

AUTHORED ARTICLE IMAGE
assets/uploads/articles/YYYY/MM/article-slug/

RESPONSIVE DERIVATIVE
assets/generated/posts/YYYY/MM/article-slug/

ARTICLE VIDEO
GitHub Release asset: writer-media-YYYY-MM

Legacy image sources and their established generated URLs remain unchanged. The responsive-image generator now uses scripts/media-paths.mjs, which keeps legacy output flat while routing future article-owned derivatives into matching article namespaces.

scripts/check-content.mjs now validates generated responsive images recursively so nested derivatives receive the same size checks as legacy flat output.

Stage 3 also added:

The image optimizer completed successfully, Writer production smoke passed, Site Quality passed including the new media check, and GitHub Pages built successfully before Stage 3 was closed.

Stage 4 Writer frontend modules

Stage 4 keeps the browser contract unchanged:

/write/
  → /assets/writer.js

The maintainable source now lives under _writer/:

_writer/
  00-core.js
  01-preview.js
  02-state-library.js
  03-publishing.js
  04-editor-tools.js
  05-media.js
  06-bootstrap.js

scripts/build-frontend-bundles.mjs concatenates those ordered source modules into the existing assets/writer.js compatibility bundle. This deliberately preserves the Writer’s shared closure and runtime ordering instead of introducing a risky browser-module rewrite.

The split reduced the single-file maintenance surface into domains for core/frontmatter helpers, preview rendering, state/library/GitHub transport, publishing, editor tools, media upload/layout, and event/bootstrap behavior.

Safeguards added in Stage 4:

The generated bundle was verified byte-for-byte against the ordered source fragments. Writer auth quality passed, production Writer smoke passed, Site Quality passed the generated-bundle check, and GitHub Pages built successfully before Stage 4 was closed.

Planned stages

Stage Scope Status
0 Baseline, rollback marker, reference audit Complete
1 Permanent organizational rules Complete
2 Future article asset upload hierarchy Complete
3 Media source/generated/video pipeline separation Complete
4 Writer frontend module split Complete
5 Development-script organization Next
6 GitHub Actions workflow consolidation Pending
7 Legacy/V2/V3 page cleanup Pending
8 Runtime-data and cache policy Pending
9 Repository integrity enforcement Pending
10 Final documentation and maintenance mode Pending

The status table is updated at the end of every completed stage.