rdmsm4x-changelog-20260915-1740-dev-root-CLAUDE-md-orientation-section

2026-09-15 17:40:04 EDT · rdmsm4x · session_012cXdr2uPhnPS1cQfbt9pPQ

CORRECTION 2026-09-15 21:4x EDT — the bitROO finding in this record is WRONG and is retracted. apps/bitROO/CLAUDE.md is a symlink to ../CLAUDE.md (index mode 120000, in place since 2026-08-22 18:12), not a byte-identical copy. shasum and stat FOLLOW symlinks, so it hashed identical to its own target and reported a different inode with links=1 — indistinguishable from a real duplicate. The symlink is the CORRECT pattern: it cannot drift, so bitROO inherits every apps/CLAUDE.md fix automatically. Acting on the finding would have replaced a working symlink with a real file and CREATED the divergence it warned about. A full re-sweep with find -type f found 192 regular-file CLAUDE.md and zero ancestor/descendant duplicate pairs tree-wide. Ticket DOC-20260915-01 was opened, then resolved INVALID with the disproving measurement. ~/dev/CLAUDE.md section 4 now documents the symlink pattern and the measurement trap instead. Everything else in this record stands as written and was re-verified.

Added a verified engineering-orientation section to the canonical ~/dev/CLAUDE.md, which previously contained coordination policy only and no codebase documentation. Rich's policy text is unchanged byte-for-byte; the new section is prepended above it.

Scope

• Host: rdmsm4x (canonical hub). Fleet-wide in effect, because ~/dev/CLAUDE.md is inherited by every agent working any project under ~/dev on any of the six Macs.
• Files touched: /Users/richh/dev/CLAUDE.md (17,460 -> 29,067 bytes).
• Nothing else created, moved, or deleted. ~/dev is not a git repo, so there is no commit.

What was added

A # ~/dev — what this tree is, and how to work in it section, 8 subsections:

1. Hub-of-repos reality: 187 independent repos, per-domain counts, no root build/test/git.
2. Reading order on landing, and which large root docs NOT to load whole (MORNING-START-HERE.md 89 KB, root ISSUES.md 56 KB, PROJECTS.md is a banner log). Table of the _-prefixed operational directories.
3. Build and test: canonical universal2 SwiftPM command, the lipo -archs gate, build.sh pattern, lib/four_platform_gate.zsh; the three build checks that cannot fail; uv/pytest and the env-var hermeticity of root tests/; record counts not "green".
4. Per-project doc-set convention with measured prevalence; the CLAUDE.md walk-up chain.
5. ticket CLI as the concurrency control (claim leases), with the command set.
6. Shell traps measured live on this host (see Evidence).
7. Fleet scripts: dev_update.zsh v1.99 self-containment rationale, ~/bin worktree helpers.
8. The pre-existing double "rule 28" numbering, documented rather than renumbered.

Verification evidence

• Original policy intact: extracted the suffix from ^# Global agent cooperation policy$ to EOF and cmp-compared against a pre-edit copy — IDENTICAL, zero bytes altered. Both rule-28 lines still present at lines 247 and 296. 30 numbered rule items before and after.
• Counts asserted in the doc, all re-measured: 187 repos (depth<=4, excluding _*, archive/, .build/, checkouts/); apps 68, lib 29, concepts 20, sites 11, arista 8, net 7, fleet 7; 36 Package.swift, 10 .xcodeproj, 14 build.sh under apps/ (worktrees excluded); tickets 475 open / 465 resolved; _worktrees 159, _handoff 389.
• Toolchain: Swift 6.4 (swiftlang-6.4.0.34.1), Xcode 27.0 (27A266a), xcode-select -p = /Applications/Xcode-27.0-RC.app/Contents/Developer.
• Shell options verified live, not assumed: [[ -o nomatch ]] = ON, [[ -o bareglobqual ]] = OFF, [[ -o extendedglob ]] = OFF. Reproduced the failure (print -l foo/*(N) -> no matches found: foo/*(N)) and confirmed both documented workarounds succeed (setopt null_glob -> empty expansion rc=0; setopt bare_glob_qual -> (N) honored rc=0).
• Duplicate-inheritance defect confirmed by hash: apps/CLAUDE.md and apps/bitROO/CLAUDE.md are both SHA-256 baf3f942a656fcd08d6e790742c4655fc32558da1ee9ef82dbb202b167b2b4b9. Documented as a known defect; NOT fixed in this session.
• Heading tree of the new section rendered and inspected; no heading reparented.

Backup / how to undo

Pre-edit copy: /private/tmp/claude-501/-Users-richh-dev/024d2323-7537-4953-8a33-302e8fc2387d/scratchpad/CLAUDE.md.bak-20260915-173758 (session scratchpad — NOT durable across reboot). To revert, delete everything above and including the --- separator that precedes # Global agent cooperation policy; the file below that line is the original in full.

Outstanding owner actions

• None required. Two items surfaced for the backlog, neither actioned:
  1. apps/bitROO/CLAUDE.md should inherit apps/CLAUDE.md rather than duplicate it.
  2. The policy's double "rule 28" numbering is Rich's to renumber.

No secrets, credentials, tokens, or signed URLs appear in this record or in the edited file.