docs/repo-cleanup-pass #103

Merged

starsetbyte merged 16 commits from docs/repo-cleanup-pass into main 2026-07-26 03:20:13 +00:00

Conversation 0 Commits 16 Files changed 64 +5009 -192

starsetbyte commented 2026-07-26 03:14:21 +00:00

Owner

Copy link

Summary

Brings the repository's recorded state into agreement with its actual state at 9e2d705, and prepares the branch/PR debt for retirement. No production code changed.

The problem was authority drift: several competing descriptions of the same repository, each written from another document rather than from source. AGENTS.md still asserted the PDS was hardcoded to bsky.social — the limitation OAuth removed. CLAUDE.md told readers no CI workflow file existed when .forgejo/workflows/ci.yml is checked in and authoritative. Three documents reported three different test counts, none of them current. The design specification existed only in an ephemeral cache directory.

What changed

Area	Change
Design specification	Imported into version control — 1107 lines + 2 assets, previously the sole copy lived in ~/.hermes/cache/. SHA-256 verified against a manifest before and after copy.
Messaging research	4 documents restored (reverted off main on July 11), with a sourced re-verification table naming the four AT Protocol sources checked on 2026-07-25
PR-review remediation plan	Landed as historical record, 412 lines
Documentation tree	Root reviews/ folded into docs/reviews/; docs/superpowers/{plans,specs} dissolved into docs/{plans,specs}. 34 files moved via git mv, 46 path references repaired
Status vocabulary	59 documents each carry exactly one of four values — Current guidance, Historical record, Reference/evidence, Superseded — plus docs/README.md, a 75-row index
AGENTS.md	148-line fossil → 16-line pointer at CLAUDE.md. A pointer cannot drift.
CLAUDE.md	CI section rewritten against the real workflow; test count and Coil version corrected; new section recording the July 12–13 concurrency and account-boundary invariants
README.md	Counts corrected to 151 / 710 / 92, stamped at 9e2d705
Consolidated roadmap	Stale P0 (`
Reconciliation ledger	New: docs/reviews/2026-07-25-branch-pr-reconciliation.md — 58 branch rows and 10 PR rows, each with its safety command and that command's output

Verification

Check	Result
Changed-path allowlist	PASS — documentation only. Nothing under app/, gradle/, .forgejo/, or any build file.
Gate	tests=710 failures=0 errors=0 skipped=0 classes=92 — identical to the pre-pass baseline
Lint	0 errors, 133 warnings — unchanged
Document census	57 → 67, every difference reconciled as a rename or an intentional addition. Nothing lost.
Design import	Both PNG SHA-256 match the manifest byte-for-byte
Links	Zero dangling, across inline, image, and reference-style links
Status vocabulary	Exactly four values, no document missing a header

Defects caught in review

Five, none of which the obvious check would have found:

1. The design import replaced the document's own metadata block instead of inserting above it — deleting its "proposed target state" caveat. Sole symptom: 254 bytes smaller than source despite gaining a header.
2. A fix that existed in the working tree but was never staged — a commit whose message described content it did not contain.
3. A context-blind find-and-replace corrupted the two documents that describe the find-and-replace, turning a data-loss-preventing collision check into a no-op.
4. CLAUDE.md asserted "every mute/block mutation uses update {}". False — muteThread/unmuteThread use plain read-then-write. Corrected to state what the code does, and why the thread-mute pair is deliberately different.
5. The pass's own plan was statused Historical record while still executing.

Two of these originated in the plan rather than the implementation. Both are corrected in the plan as well, so a re-run cannot reintroduce them.

Not in this PR

docs/pr-review-remediation-plan's content reaches main only through this merge — its own commits are not ancestors of main. Branch deletion is deliberately gated on this PR landing; deleting it beforehand would destroy the only copy.

Branch and PR cleanup (56 deletions, 10 PR actions) is a separate follow-up, authorized by the ledger and gated on this merge.

---

🤖 Generated with Claude Code

https://claude.ai/code/session_01MQ56Mh1F6otBp3a4pRWm5Y

## Summary Brings the repository's recorded state into agreement with its actual state at `9e2d705`, and prepares the branch/PR debt for retirement. **No production code changed.** The problem was authority drift: several competing descriptions of the same repository, each written from another document rather than from source. `AGENTS.md` still asserted the PDS was hardcoded to `bsky.social` — the limitation OAuth removed. `CLAUDE.md` told readers no CI workflow file existed when `.forgejo/workflows/ci.yml` is checked in and authoritative. Three documents reported three different test counts, none of them current. The design specification existed only in an ephemeral cache directory. ## What changed | Area | Change | |---|---| | **Design specification** | **Imported into version control** — 1107 lines + 2 assets, previously the sole copy lived in `~/.hermes/cache/`. SHA-256 verified against a manifest before and after copy. | | Messaging research | 4 documents restored (reverted off `main` on July 11), with a sourced re-verification table naming the four AT Protocol sources checked on 2026-07-25 | | PR-review remediation plan | Landed as historical record, 412 lines | | Documentation tree | Root `reviews/` folded into `docs/reviews/`; `docs/superpowers/{plans,specs}` dissolved into `docs/{plans,specs}`. 34 files moved via `git mv`, 46 path references repaired | | Status vocabulary | 59 documents each carry exactly one of four values — `Current guidance`, `Historical record`, `Reference/evidence`, `Superseded` — plus `docs/README.md`, a 75-row index | | `AGENTS.md` | 148-line fossil → 16-line pointer at `CLAUDE.md`. A pointer cannot drift. | | `CLAUDE.md` | CI section rewritten against the real workflow; test count and Coil version corrected; new section recording the July 12–13 concurrency and account-boundary invariants | | `README.md` | Counts corrected to 151 / 710 / 92, stamped at `9e2d705` | | Consolidated roadmap | Stale P0 (`|| true` false-green CI) closed with per-item evidence; currency note added | | Reconciliation ledger | New: `docs/reviews/2026-07-25-branch-pr-reconciliation.md` — 58 branch rows and 10 PR rows, each with its safety command and that command's output | ## Verification | Check | Result | |---|---| | **Changed-path allowlist** | **PASS — documentation only.** Nothing under `app/`, `gradle/`, `.forgejo/`, or any build file. | | Gate | `tests=710 failures=0 errors=0 skipped=0 classes=92` — identical to the pre-pass baseline | | Lint | 0 errors, 133 warnings — unchanged | | Document census | 57 → 67, every difference reconciled as a rename or an intentional addition. Nothing lost. | | Design import | Both PNG SHA-256 match the manifest byte-for-byte | | Links | Zero dangling, across inline, image, and reference-style links | | Status vocabulary | Exactly four values, no document missing a header | ## Defects caught in review Five, none of which the obvious check would have found: 1. The design import **replaced** the document's own metadata block instead of inserting above it — deleting its "proposed target state" caveat. Sole symptom: 254 bytes smaller than source despite gaining a header. 2. A fix that existed in the working tree but was never staged — a commit whose message described content it did not contain. 3. A context-blind find-and-replace corrupted the two documents that *describe* the find-and-replace, turning a data-loss-preventing collision check into a no-op. 4. `CLAUDE.md` asserted *"every mute/block mutation uses `update {}`"*. False — `muteThread`/`unmuteThread` use plain read-then-write. Corrected to state what the code does, and why the thread-mute pair is deliberately different. 5. The pass's own plan was statused `Historical record` while still executing. Two of these originated in the plan rather than the implementation. Both are corrected in the plan as well, so a re-run cannot reintroduce them. ## Not in this PR `docs/pr-review-remediation-plan`'s content reaches `main` **only** through this merge — its own commits are not ancestors of `main`. Branch deletion is deliberately gated on this PR landing; deleting it beforehand would destroy the only copy. Branch and PR cleanup (56 deletions, 10 PR actions) is a separate follow-up, authorized by the ledger and gated on this merge. --- 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01MQ56Mh1F6otBp3a4pRWm5Y

starsetbyte added 16 commits 2026-07-26 03:14:21 +00:00

docs: design for the repo and documentation cleanup pass ... 52f063bd44

Records the approved design for reconciling the repository's documented
state with its actual state at 9e2d705, and retiring the branch and
pull-request debt from the June-July work.

Four workstreams: Forgejo PR/branch reconciliation, landing the messaging
research and PR-review remediation plan, consolidating the docs tree with
an index, and correcting the four agent-facing documents.

No production code changes. Ground truth measured by running the gate,
not by reading existing documents - documents citing documents is what
produced the drift being corrected.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MQ56Mh1F6otBp3a4pRWm5Y

docs: harden cleanup-pass design after review ... 0d080325d5

Turns three implicit safeguards into enforceable ones and closes a
vocabulary gap.

- changed-path allowlist: the gate proves the tree passes, not that no
  production code changed. The branch diff may touch only the four
  agent-facing docs and docs/**; anything under app/, gradle/, .forgejo/
  or build config fails the pass outright.
- exact manifest for the design-spec import: three source paths with
  byte sizes and SHA-256, hard stop on any absent source or hash
  mismatch. The point is rescuing an authority document from ephemeral
  storage, so it cannot depend on identifying the right-looking PNG.
- durable reconciliation ledger for branch and PR administration,
  landed in two stages since workstream A runs post-merge.

Also: closed the status vocabulary at four values with a header template
for each; defined link verification precisely (reference-style and image
links in scope, external URLs and fenced code excluded); recorded the
verified path sets for the revert and cherry-pick commits, all four
clean; captured AT Protocol source URLs for the messaging re-verification
rather than asserting "re-verified"; corrected the git mv claim, which
preserves rename detectability rather than recording a rename.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MQ56Mh1F6otBp3a4pRWm5Y

docs: implementation plan for the repo and documentation cleanup pass ... c203673bce

Twelve tasks across 77 steps. Tasks 1-11 are one documentation-only pull
request; Task 12 is irreversible Forgejo administration gated on that PR
having merged, since two branches slated for deletion carry content it
lands.

Every task carries its own verification command with an expected result.
The load-bearing one is Task 11 Step 1: a changed-path allowlist run
against the full branch diff, which is what actually proves no production
code changed - the Gradle gate only proves the resulting tree passes.

Notable during authoring: the repository's entire markdown-link surface
is two links, both unaffected by the moves, but 31 stale path references
live in inline code spans across 15 files. A link-only sweep would have
missed all of them.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MQ56Mh1F6otBp3a4pRWm5Y

docs: restore AT Protocol messaging research (#80, #95) ... 69adf55b24

Reverts c31980e, which removed the four research documents from main on
July 11. Adds Reference/evidence status headers and a re-verification
section recording the four AT Protocol sources checked on 2026-07-25.

All original conclusions hold. One development postdates the research:
granular permission sets are rolling out to replace the transitional
scopes, noted against Decision 4.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

docs: land PR-review remediation plan as historical record (#101) ... a01984c45f

Restores the 398-line remediation plan from
docs/pr-review-remediation-plan and marks it as a historical record: all
13 tasks completed and merged between 2026-07-12 and 2026-07-13.

Notes that #97-#100 show as closed-unmerged on Forgejo because the
branches were integrated locally with --no-ff merges.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

docs: import the design specification into version control ... 92b317cbfc

The 1107-line design specification and its two reference images existed
only in ~/.hermes/cache/documents/, one cache eviction from being lost.
It is the authority for the label system, the 44/48dp touch-target rule,
and the component adoption order - all inputs to the post-card and
profile work scheduled next.

Verified by SHA-256 against the source manifest before and after copy.

Status is Reference/evidence, not Current guidance: the document
self-describes as a proposed target state whose own caveat says source
code remains authoritative for shipped behavior.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

docs: correct the plan's design-spec status assignment ... 3109ba6913

Amends Task 4 Step 4 and Task 6's assignment table after execution
surfaced a plan error: the plan assigned `Current guidance` to
docs/design/design.md, but that document self-describes as a proposed
target state whose own caveat says source code remains authoritative for
shipped behavior. Human partner ruled the document's framing governs.

Also rewrites Step 4 to say insert-do-not-replace, with a byte-level
proof requirement. The first attempt overwrote the document's existing
metadata block; the only symptom was the file ending up 254 bytes
smaller than its source despite gaining a header. A line count would not
have caught it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

docs: consolidate the documentation tree ... 11bed631ae

Folds root reviews/ into docs/reviews/ (5 documents) and
docs/superpowers/{plans,specs}/ into docs/{plans,specs}/ (36 documents).
One tree, one place per kind of document.

Repairs 31 stale path references across 15 files. These live in inline
code spans rather than markdown links, so a link-only sweep would have
missed every one of them - the repository's entire markdown-link surface
is two links, both into docs/reviews/, both unaffected by these moves.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

docs: status headers on every document, plus the index ... 7a0eceee56

Assigns exactly one of four statuses - Current guidance, Historical
record, Reference/evidence, Superseded - to every document under docs/,
and adds docs/README.md as the map.

The vocabulary is deliberately closed at four values. An open set is how
the previous taxonomy fossilised into two review directories and two plan
directories with no way to tell live guidance from finished work.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

docs: reduce AGENTS.md to a pointer at CLAUDE.md ... 392d779e74

The file was a June fork of CLAUDE.md that had drifted badly: it still
claimed the PDS was hardcoded to bsky.social and that self-hosted users
could not authenticate - the exact limitation the OAuth/DPoP work
removed - plus schema v4/v7 against an actual v12, Coil 3.0.4 against
3.2.0, and moderation listed as in progress two months after it shipped.

Codex reads this file. A pointer cannot drift; a duplicate always will.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

docs: correct CLAUDE.md against the codebase at 9e2d705 ... 0cfa17bc66

Three factual errors, each verified against source rather than against
another document:

- the CI section told the reader there is no workflow file in-repo and
  not to go looking. .forgejo/workflows/ci.yml exists, has three jobs,
  and is authoritative. Rewritten with the actual job structure and the
  reason the instrumented job is disabled.
- test count ~540/73 files -> 710/92 test classes, stamped at 9e2d705
- Coil 3.0.4 -> 3.2.0

Adds a concurrency and account-boundary invariants section recording the
July 12-13 adversarial-review outcomes: the account epoch, striped locks,
URI-keyed interaction authority, atomic moderation mutations and the
hydration mutex, cancellation-safe reverts, no blocking construction,
and allowBackup=false. These are silently breakable and each one closed
a traced defect.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

docs: correct the plan's atomicity invariant ... 77e2091c6a

The plan asserted "every mute/block mutation uses `update {}`, never
read-then-write." False: ModerationActionsRepository's muteThread and
unmuteThread use plain `.value = .value +/- rootUri`, reverts included.
Only the six account mutations use update{}.

The bullet contradicted itself two lines apart, since its own next clause
correctly excluded the thread-mute pair from the hydrationMutex. Caught
in review by checking the claim against the Kotlin rather than against
the brief - the documents-citing-documents failure this pass exists to
remove, reproduced inside the pass.

Corrected here and in CLAUDE.md so a re-run cannot reintroduce it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

docs: correct README counts and close the roadmap's stale P0 ... 7e61f89fe1

README: 149 files/632 tests/85 test files -> 151/710/92, stamped at
9e2d705 and measured from the JUnit XML rather than copied.

Roadmap: the P0 'Forgejo release check is false-green' described a
|| true mask that no longer exists - ci.yml runs bundleRelease and
assembleRelease unmasked, generates disposable CI signing material, and
uploads checksummed artifacts with if-no-files-found: error. Marked
closed with per-item evidence, and a currency note pointing at the
July 12-13 remediation for everything the July 11 snapshot predates.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

docs: branch and PR reconciliation ledger, planned dispositions ... 4825efc8d4

Records every branch and pull request with its safety-check command, that
command's result, and its planned disposition, ahead of any deletion.

Branch deletion on the server is irreversible and terminal output
evaporates. The safety test is 'git log main..<branch>' returning empty,
per branch - never the branch name, never a --merged listing, which can
mislead after a rebase.

Execution is confirmed by a follow-up commit once workstream A runs.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

docs: gate one branch deletion on this pass merging ... f9a20fc3ee

Task 10's review found that docs/pr-review-remediation-plan is the only
branch whose supersession is contingent: its 398-line document reaches
main solely through this pass merging. Its own commits are not ancestors
of main, so deleting it beforehand would destroy the only copy.

Adds an explicit gate to Task 12 Step 5 with a command that halts if the
merge did not land, and records the contrast with feat/messaging-research
- same surface shape, but its commits ARE ancestors of main, so its
blobs stay reachable regardless.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

docs: fix wave from final whole-branch review ... 69c9a83f92

Eight documentation fixes surfaced by the closing review of this pass:

- README.md: Coil 3.0.4 -> 3.2.0, matching CLAUDE.md and libs.versions.toml
  (hilt/room versions checked too, both already correct).
- Two self-reports of this pass's own progress (the plan file and its
  docs/README.md index row) still said "tasks 1-6 complete, 7-12 remain" -
  updated to reflect tasks 1-10 complete, 11 executing, 12 gated on merge.
- docs/README.md was missing a row for the branch/PR reconciliation ledger
  and undercounted the docs/ tree at 66 files (actual: 67).
- The reconciliation ledger's own header claimed "Historical record -
  completed" while its Execution section still read as not-yet-run -
  restatused to Current guidance with an explicit "nothing has executed
  yet" callout, since it authorizes a pending irreversible deletion of
  56 branches.
- README and CLAUDE.md pointed readers at the now-superseded
  MVP_IMPLEMENTATION_PLAN.md as "the roadmap" - reworded to send readers
  to the live consolidated-roadmap-and-review.md instead.
- moderation-remaining-work.md's preserved "**Status:** roadmap, not an
  executable task list" line mimicked the closed status vocabulary -
  relabeled to "**Nature:**", nothing else touched.
- The consolidated roadmap narrated its closed P0 in present tense before
  its closure note - moved the closure note to the top of the section, and
  ticked three checklist items and one already-clean whitespace item that
  this pass completed but never marked off.
- The adversarial delta review's release checklist was missing a row for
  P2-4 (bounded per-post lock storage), which shipped in ac65ef2 and is
  live at InteractionRepository.kt:113-117 - added with an explicit
  "row added 2026-07-25" annotation per the doc's own re-statusing rule.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

starsetbyte merged commit d9af65c9b9 into main 2026-07-26 03:20:13 +00:00

starsetbyte referenced this pull request from a commit 2026-07-26 03:20:15 +00:00

Merge pull request 'docs/repo-cleanup-pass' (#103) from docs/repo-cleanup-pass into main

starsetbyte referenced this pull request 2026-07-26 03:22:31 +00:00

fix: notification accessibility, locale-aware timestamps, release checklist (P2-5, P2-6) #100

starsetbyte referenced this pull request 2026-07-26 03:22:31 +00:00

fix: async-safe repository construction, backup policy, moderation hydration + cancellation (P1-5, P1-6, P2-1, P2-2) #99

starsetbyte referenced this pull request 2026-07-26 03:22:31 +00:00

fix: authoritative interaction state, cancellation-safe rollback, bounded locks (P1-1, P2-2, P2-4) #98

starsetbyte referenced this pull request 2026-07-26 03:22:31 +00:00

fix: DPoP nonce handling, did:web resolution, PAR request_uri encoding (P1-2, P1-3, P1-4, P2-3) #97

starsetbyte referenced this pull request 2026-07-26 03:22:32 +00:00

chore: integrate device-trust continuation into main #79

starsetbyte referenced this pull request 2026-07-26 03:22:32 +00:00

fix: establish account operation lifecycle boundary #102

starsetbyte referenced this pull request 2026-07-26 03:22:32 +00:00

docs: plan remediation for July 12 PR review findings #101

starsetbyte referenced this pull request 2026-07-26 03:22:33 +00:00

docs: record July 11 adversarial delta review #96

starsetbyte referenced this pull request 2026-07-26 03:22:33 +00:00

docs: AT Protocol messaging research (#80) #95

starsetbyte referenced this pull request 2026-07-26 03:22:34 +00:00

WIP: feat/moderation #11

starsetbyte referenced this pull request from a commit 2026-07-26 03:26:01 +00:00

docs: record Task 12 execution, close the cleanup pass

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels   

auth

Authentication and OAuth

  

bug

Something is broken

  

composer

Post composition and drafts

  

correctness

Logic and state correctness

  

database

Room, migrations, persistence

  

durability

Data safety, persistence, recovery

  

enhancement

New feature or request

  

feeds

Feed management and preferences

  

interactions

Like, repost, reply interactions

  

notifications

Notification system

  

performance

Performance issues

  

reliability

Resilience against interruptions

  

safety

User safety and trust

  

security

Security concerns

No labels

auth

bug

composer

correctness

database

durability

enhancement

feeds

interactions

notifications

performance

reliability

safety

security

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

starsetbyte/peregrine!103

No description provided.