Repository navigation
docs: make the repo self-sufficient for a cold session (migration readiness, round 1) - #26
Merged
Merged
Conversation
Blind-reader audit of a fresh clone (round 1) found the gaps below; this closes them so a session with no machine-local memory can resume from the repo alone: - MEMORY.md (new): successor briefing ranked below CLAUDE.md — pinned resume point (#14 next, queue order), what just happened, off-repo context (vendored consumers, upstream/mirror rule, pending byteorb umbrella task), new-machine bootstrap. - CLAUDE.md: read order for fresh sessions; layout table gains docs/superpowers/specs/, LEARNINGS.md, MEMORY.md, CHANGELOG.md; stale '155 scenarios' corrected (54 scenarios / 298 assertions as of v1.4.0); roadmap now points at the issue tracker + MEMORY.md; conventions gain branch/PR flow, issue-vs-PR numbering, and the TDD/spec-doc norm. - README.md: layout table same corrections. The audit also found validate silently ignoring unknown argv — filed as #25 rather than fixed here (behavior change, separate concern). Claude-Session: https://claude.ai/code/session_01UquRBmRrh52iyPFuFQna5q
budhash
added a commit
that referenced
this pull request
Jul 16, 2026
Second blind cold-clone audit (after #26) found four residuals: - examples/TASKS.md predated milestones despite being billed as fully populated: add a # Milestones registry (M1/alpha, M2/beta), assign @milestone via the CLI (F-0001 -> m1, T-0004 -> beta), and add @milestone= to the Meta tag list. Still validates; rollup works. - CHANGELOG v1.0.0 '155-scenario' mislabel: additive editor's note (155 counted assertions; suite was 30 scenarios / 155 assertions) — entries stay unrewritten per convention. - MEMORY.md overclaimed that every design decision has an in-repo spec; now states the milestone spec lived off-repo (taxjot) and where its surviving spec/rationale actually are. - Wording: 'make test prints the live assertion count' (it does not print scenario counts); CLAUDE.md releasing now lists gh release create as standard practice (matches every release since v1.1.0). Claude-Session: https://claude.ai/code/session_01UquRBmRrh52iyPFuFQna5q
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Preparing a machine move: the repo must carry everything a fresh session needs, since machine-local memory won't travel. A blind reader (fresh agent, zero context, fresh clone of main) audited the repo and answered a resume questionnaire; this PR closes the gaps it found.
Findings → fixes
make testfor the live countLEARNINGS.md,MEMORY.md,docs/superpowers/specs/,CHANGELOG.mdMEMORY.md, which pins the resume point (#14 next, agreed v1 scope, queue order after it)#Nvs(#N)) and thedocs/superpowers/name unexplainedMEMORY.md(explicitly ranked below CLAUDE.md)validatesilently ignores unknown argv and exits 0 (real code finding)Not changed on purpose
Historical CHANGELOG entries (including v1.0.0's "155-scenario" phrasing) — the changelog is a record; present-tense docs are the ones that must be true.
make checkgreen (298/298). Round 2 blind read runs after this merges.https://claude.ai/code/session_01UquRBmRrh52iyPFuFQna5q