Skip to content

docs: retire PROGRESS.md and archive the frozen HARNESS_DESIGN spec - #118

Merged
codexceed merged 1 commit into
mainfrom
docs/retire-progress-freeze-design
Jul 17, 2026
Merged

codexceed merged 1 commit into
mainfrom
docs/retire-progress-freeze-design

Conversation

@codexceed

Copy link
Copy Markdown
Owner

Description

Retires the two originating design docs that the ADR log and ARCHITECTURE.md have superseded. PROGRESS.md is deleted; HARNESS_DESIGN.md is frozen (banner) and moved to docs/archive/, with all living navigation repointed.

Motivation

Both docs had drifted into stale roles:

  • PROGRESS.md (phased build ledger) duplicates status that now lives more accurately in ARCHITECTURE.md's per-component status markers and CHANGELOG.md.
  • HARNESS_DESIGN.md was billed as "source of truth," but the ADRs under docs/adr/ are the living design log and already win on conflict; the spec had fallen behind the as-built system.

It is frozen and archived rather than deleted because ~two dozen ADRs anchor to its §N sections as their originating rationale — those citations must keep resolving.

Changes

  • Delete PROGRESS.md.
  • Freeze HARNESS_DESIGN.md with a DECISIONS.md-style "do not edit" banner redirecting to the ADRs (design) and ARCHITECTURE.md / CHANGELOG.md (status / what-shipped), and move it to docs/archive/HARNESS_DESIGN.md.
  • Rewrite the moved file's internal relative links for its new depth (docs/adr/ → ../adr/, ARCHITECTURE.md/CHANGELOG.md → ../../…).
  • Repoint the living navigation docs at the new location + the ADRs: CLAUDE.md doc-map (drop the PROGRESS.md row; reframe the design-spec row as frozen/archived), ARCHITECTURE.md, README.md (status line + design-depth footer), jo-cli/ARCHITECTURE.md, and avatar/__init__.py.
  • Left untouched: the HARNESS_DESIGN.md §N bare-name prose citations across the ADRs, DECISIONS.md, and the blogging archive — they are a stable citation key, not clickable links, so nothing breaks (same hands-off treatment as the frozen DECISIONS.md).

Testing

  • Docs-only change (plus one module-docstring edit); no runtime code paths affected.
  • Pre-commit gate green: ruff check, ruff format, compileall, pyrefly, pydoclint, deptry all passed.
  • Verified no markdown link anywhere still targets the old repo-root HARNESS_DESIGN.md path, and no living doc still references the deleted PROGRESS.md.

Retire the two originating docs now superseded by the ADR log +
ARCHITECTURE.md:

- Delete PROGRESS.md (phased build ledger). Build status now lives in
  ARCHITECTURE.md's status markers; what-shipped is CHANGELOG.md.
- Freeze HARNESS_DESIGN.md with a DECISIONS.md-style banner and move it
  to docs/archive/ — kept (not deleted) because ~two dozen ADRs anchor to
  its §N sections. ADRs are the living design log; it wins on conflict.
- Repoint the living navigation docs (CLAUDE.md doc-map, ARCHITECTURE.md,
  README.md, jo-cli/ARCHITECTURE.md, avatar/__init__.py) at the new
  location and at the ADRs. Fix the moved file's internal relative links.

ADR / DECISIONS.md prose citations keep the bare-name §N shorthand.
@codexceed

Copy link
Copy Markdown
Owner Author

Optional PR quiz (self-assessment)

Offered per the repo's soft-gate rule; skipped, so posting the questions with answers for the record.

1. Why was HARNESS_DESIGN.md frozen-and-archived rather than deleted outright (as PROGRESS.md was)?
Because ~two dozen ADRs cite its §N sections as their originating rationale, so the file must keep existing for those citations to resolve. PROGRESS.md has no such inbound §N anchors, so it was safe to delete.

2. After the move, what is the new canonical source for (a) why the build is shaped as it is and (b) what's built / what shipped?
(a) The ADRs under docs/adr/ (the living design log — they win on conflict with the frozen spec). (b) ARCHITECTURE.md's per-component status markers for what's built, and CHANGELOG.md for what shipped.

3. The ~23 ADR references to HARNESS_DESIGN.md were left unchanged. Why does that not create broken links?
They are bare-name prose shorthand (e.g. `HARNESS_DESIGN.md` §13), not clickable markdown links, so relocating the file breaks nothing — same hands-off treatment given the frozen DECISIONS.md. Only the single real inbound link (in README.md) needed repointing.

@codexceed codexceed self-assigned this Jul 17, 2026
@codexceed
codexceed merged commit bc1d8b4 into main Jul 17, 2026
1 check passed
@codexceed
codexceed deleted the docs/retire-progress-freeze-design branch July 17, 2026 15:27
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.

2 participants