docs: retire PROGRESS.md and archive the frozen HARNESS_DESIGN spec - #118
Conversation
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.
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 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? 3. The ~23 ADR references to |
Description
Retires the two originating design docs that the ADR log and
ARCHITECTURE.mdhave superseded.PROGRESS.mdis deleted;HARNESS_DESIGN.mdis frozen (banner) and moved todocs/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 inARCHITECTURE.md's per-component status markers andCHANGELOG.md.HARNESS_DESIGN.mdwas billed as "source of truth," but the ADRs underdocs/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
§Nsections as their originating rationale — those citations must keep resolving.Changes
PROGRESS.md.HARNESS_DESIGN.mdwith aDECISIONS.md-style "do not edit" banner redirecting to the ADRs (design) andARCHITECTURE.md/CHANGELOG.md(status / what-shipped), and move it todocs/archive/HARNESS_DESIGN.md.docs/adr/→../adr/,ARCHITECTURE.md/CHANGELOG.md→../../…).CLAUDE.mddoc-map (drop thePROGRESS.mdrow; reframe the design-spec row as frozen/archived),ARCHITECTURE.md,README.md(status line + design-depth footer),jo-cli/ARCHITECTURE.md, andavatar/__init__.py.HARNESS_DESIGN.md §Nbare-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 frozenDECISIONS.md).Testing
ruff check,ruff format,compileall,pyrefly,pydoclint,deptryall passed.HARNESS_DESIGN.mdpath, and no living doc still references the deletedPROGRESS.md.