Skip to content

Commit 4 BINDING design specs into docs/proposals/mockups/ for durability - #441

Merged
WilfordGrimley merged 1 commit into
masterfrom
worktree-agent-ae8b82ec537ab35cc
Jul 24, 2026
Merged

Commit 4 BINDING design specs into docs/proposals/mockups/ for durability#441
WilfordGrimley merged 1 commit into
masterfrom
worktree-agent-ae8b82ec537ab35cc

Conversation

@WilfordGrimley

Copy link
Copy Markdown

Description

A durability gap: four BINDING, owner-approved design specs (rail-delegacy, editor-polish, cardback-pdfwait, wtc-rebuild) lived only in a session's tmp dir — which does not survive past that session — while committed code comments across the repo already cite each spec by filename as its authority. Same failure mode docs/reference/funnel-spec.md was recovered from during the 2026-07-23 D-lettering sweep. This PR brings all four into the repo, following the docs/proposals/mockups/proposal-h/ precedent (spec + companion static-HTML mockup, one directory per round).

What shipped

  • docs/proposals/mockups/{rail-delegacy,editor-polish,cardback-pdfwait,wtc-rebuild}/SPEC-*.md + each spec's companion mockup HTML (*-mockup.html), copied verbatim (including OWNER AMENDMENTS sections where present — editor-polish and cardback-pdfwait have one, rail-delegacy/wtc-rebuild don't).
  • Screenshots/PNGs deliberately not copied (bulk verification artifacts — each spec + its self-contained mockup HTML stands alone); wtc-rebuild's header notes this explicitly since its own line 4 mentions "+ PNGs (this dir)".
  • One-line provenance header added to each SPEC-*.md (the only content edit beyond mechanical formatting): origin date (2026-07-24), which committed files cite it by filename, and a pointer to funnel-spec.md as the precedent for this durability convention.
  • docs/proposals/mockups/README.md (new) indexes all five bundles (proposal-h/ + the four new ones) and explains why the four are here.
  • docs/README.md's Records section links the new index, so the bundle is reachable from the index chain (though proposals/mockups/ is already exempt from the orphan check as an archive-prefix bucket).

Mechanical fixes only, content otherwise verbatim

  • Ran npx prettier@2.7.1 --write on each SPEC-*.md (repo convention / pre-commit hook scope). Verified per-file: idempotent on a second pass, and diffed against the tmp originals — the only changes are table-column realignment, wrapped-prose reflow, and safe *text*_text_/bare-*\* emphasis-marker normalization (the corruption failure mode in docs/lessons.md's prettier entry — intraword-underscore breakage — does not appear anywhere in these files; none use bare underscores in prose).
  • No relative-link adjustments were needed — none of the four specs contain markdown links, and their mockup HTML files are self-contained (no relative asset references) or link only to /whatsthat/#.

Durability rationale / code-comment citation check

Per the task's ask, grepped committed code (frontend/src, MPCAutofill) for both the spec filenames and the literal tmp path:

  • SPEC-rail-delegacy.md, SPEC-editor-polish.md, SPEC-cardback-pdfwait.md are now cited by ~40 committed files on master itself (landed via Cardback reminder gate + apply-all/set-default prompts + PDF-wait experience #431, which merged onto master during this PR's session — this branch is rebased past it) — e.g. DisplayPage.tsx, SelectVersionResults.tsx, PDFGenerator.tsx, AutofillCollapse.tsx, SourcesAccordion.tsx, RequestedPrintingBadge.tsx, PrePrintSaveGate.tsx, CommonCardback.tsx, plus their test/spec files.
  • SPEC-wtc-rebuild.md is cited on the still-open PR Re-theme site to Tokyo-11 (Tokyo Night, orange action, purple accent, Semi radius) #438 (tokyo-11-retheme) branch — ChipCard.tsx, WhatsThatWords.tsx, cardPanel.tsx — not yet on master.
  • No committed code anywhere cites the raw tmp path (/home/ubuntu/.claude/jobs/...) — every citation uses the bare SPEC-*.md filename, which is exactly why bringing the specs into the repo under their original filenames resolves the citations with no code changes needed. No follow-up path-fix items to flag.

Verification

  • python3 .github/scripts/docs_lint.py --strict: clean (0 hard findings, 0 soft findings).
  • python3 .github/scripts/tests/test_docs_lint.py: 26/26 pass (includes the real-repo full-corpus check).
  • python3 .github/scripts/tests/test_publish_wiki_link_rewrite.py: 4/4 pass.
  • python3 .github/scripts/tests/test_publish_readme.py + publish_readme.py regenerate-and-diff: pass, zero drift (this PR doesn't touch readme.md's source regions).
  • npx prettier@2.7.1 --check on every changed/added markdown file: clean.
  • Pre-commit hooks (prettier, end-of-file, trailing-whitespace) ran clean on commit.
  • Deferred: no policy-text/wiki-published-page changes in this PR (docs/proposals/ is excluded from the wiki publish map), so the Policy-text and Wiki-maintenance checklist items don't apply.

Checklist

  • I have installed pre-commit and installed the hooks with pre-commit install before creating any commits.
  • I have updated any related tests for code I modified or added new tests where appropriate. (N/A — docs-only change; ran the existing docs-lint test suites above instead.)
  • I have manually tested my changes as follows: ran docs_lint.py --strict, the docs-lint/link-rewrite/readme-parity test suites, and prettier --check on every changed file (see Verification).
  • I have updated any relevant documentation or created new documentation where appropriate.

rail-delegacy, editor-polish, cardback-pdfwait, wtc-rebuild — each cited
by filename in committed code comments (the first three now on master
via PR #431) but previously living only in a session tmp dir that dies
with the session. Verbatim copies + companion mockup HTML, same
durability convention as reference/funnel-spec.md.
@WilfordGrimley
WilfordGrimley merged commit 2dc47fb into master Jul 24, 2026
9 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant