Skip to content
Crosswalker
🚧 Early alpha — building the foundation. See the roadmap →

Docs re-sync + the anti-duplication convention (CHANGELOG is the single source for delivery detail)

Created Updated

1. The incident

Section titled “1. The incident”

Milestone/roadmap pages went stale for the third time within days. Each time the cause was the same: a batch of shipped work landed, CHANGELOG.md [Unreleased] got a habit-maintained entry (per the existing reminder), but the v0.1.6 milestone page’s Phase 7 row, the milestone hub status line, ROADMAP.md, and TEST_HANDS_ON_TOUR.md were only synced occasionally — restating the same delivery detail as prose that immediately started drifting again.

Root cause: content duplication, not missing process. The CHANGELOG reminder already existed and was being followed; the milestone/roadmap pages were also restating the same facts in a second, less-maintained place.

2. The fix — single-source rule

Section titled “2. The fix — single-source rule”

Milestone pages keep only: status (🚧/✅/📋), phase structure (the table’s Phase/What-ships/Build/Manual-test columns), and acceptance criteria. In-progress delivery detail becomes a link, not a restatement: “see CHANGELOG.md [Unreleased] for the running delivery log” replaces multi-paragraph phase-row prose. Same rule for ROADMAP.md’s status section.

Applied immediately to the v0.1.6 milestone page’s Phase 7 row — a dense paragraph covering the shape workbench, render report, variadic folders, connectedness mandate, recognized-source fast path, settings hub, and workspace tab was replaced with a two-sentence summary + a link to CHANGELOG [Unreleased].

3. Written down where it will be obeyed

Section titled “3. Written down where it will be obeyed”

Added to the Documentation update reminders § Path-keyed reminders table in the repo-root CLAUDE.md (the table an agent actually consults before committing):

Landing a batch of shipped work inside an in-progress milestone (mid-milestone commits, not a full milestone close) → milestone-status flips edit the milestone page; delivery detail lives ONLY in CHANGELOG.md [Unreleased]; batch landings update CHANGELOG + flip status cells, nothing else.

This is a peer to the existing “Any commit… adds a CHANGELOG [Unreleased] entry” reminder — that row establishes CHANGELOG as canonical; this row forbids the second copy from re-forming on milestone/roadmap pages.

4. What else was re-synced in the same pass (2026-07-11, through today’s batches)

Section titled “4. What else was re-synced in the same pass (2026-07-11, through today’s batches)”

Read CHANGELOG.md’s three most-recent [Unreleased] sections (“Frameworks arrive furnished”, “The workspace tab, everywhere entry points, and one vocabulary”, “Settings hub, recognized sources, and enrichment everywhere”) as the source of truth and brought the following current instead of restating them:

  • v0.1.6 milestone page — Phase 7 row compressed per §2 above; status line updated
  • Milestone hub status snapshot line
  • Roadmap index status table + the stale “XLSX parser” / “JSON/JSONL parser” planned-v0.2 checkboxes (both shipped 2026-06-12; only JSONL remains genuinely open)
  • ROADMAP.md — mirrored the same status + Formats-section fix (the dual-source convention)
  • TEST_HANDS_ON_TOUR.md — added manual-test coverage for the vault file picker, per-import home/hub notes + Contents sections + Waypoint opt-in, the review screen’s exact-count “numeric plan”, and the folder-note-as-default placement flip
  • v0.1 schema spec §4.9 — the two generic zz-log/ index links tightened to point at this section’s sibling, the shape-workbench synthesis §3, and the CHANGELOG anchor for the furnished-frameworks batch

No content was lost — everything removed from milestone/roadmap prose exists, in more detail, in the CHANGELOG entries these pages now link to.

Section titled “Related”