[rmsharp]

@KJ5HST:

This pull request lets a project keep all of the framework's files in one directory, methodology/. Today they sit in two places: 18 at the project root, among the project's own files, and 12 under docs/methodology/. Every tool in the repository learns to find the files in either place. A project that changes nothing keeps its current locations, and a new command, bin/migrate-layout, moves a project when its owner chooses.

The numbered items I mention: #93 is my issue about the proof scripts that the ledger trimmer (methodology_trim.py) generates, which #94 fixed, and #92 added the release notes for v4.2 (both merged); #98 and #96 are my two other open pull requests; #67 was your issue about the dashboard's stale-copy warning, and #73 your pull request that fixed it. Every number below comes from a command, or is rounded from one; the scripts and their saved output are in my fork's evidence directory (the pr3, pr3b, pr4 and pr4b in their names are my own numbering, not pull request numbers). The commit hashes below are this branch's, except c8b9ddd and e7b389f, which are on my fork's main, and 65990cd, the head of #98.

What I am asking you to decide

1. Do you want the single directory? I wanted it for my own 12 projects, to clear the project root and show which files belong to the framework; I found no issue on your repository that asks for it. The 30 rows of bin/_manifest.py are 18 files at a project's root (11 that bin/sync keeps current, and 7 "seeds", which it writes once, when the project lacks them, and the project owns afterwards) and 12 documents under docs/methodology/. With the directory, all 30 sit in one place. That is the only benefit. It costs this repository: the code that decides a project's layout is copied into 11 files; 138 lines name a file by its root path on purpose and carry a same-line comment, # layout: ok -- <reason> (the "acknowledged" count of python3 bin/check-layout-literals); 36 relative links became plain names in code spans (a relative link that is right in one layout is dead in the other); and bin/migrate-layout (1,457 lines) and its 280 tests are new. It costs projects: even a project that never moves receives 19 changed files at its next bin/sync, reads two framework files that are 244 bytes larger, and finds its framework documents naming one another by bare name (28 fewer lines name docs/methodology/), with a new paragraph, the third of SESSION_RUNNER.md, saying where to look. One known gap bears on this decision: an earlier copy of the ledger pre-commit hook passes a commit with no ledger entry once the ledger has moved (see "Known gaps"). The branch is 33 commits and adds 18,367 lines.
   • If you do not want the directory, the first commit, fbcef39, can be taken alone on your current code (271 passed, 0 failed, 0 skipped and 12/12 gates, in a clean clone). The other commits sit on top of the directory work, and I have not tested them without it.
2. Which of the dashboard changes do you want? These come with the earlier work in fbcef39, and they are policy, not fixes. Please tell me which to remove and I will remove them. The other dashboard changes in fbcef39 (2.11.3 to 2.21.0) are not itemised here, except one that changes what it reports about your ratchet: since 2.21.0 it walks the gate manifest's history with git log --first-parent, so a merge no longer prints a loosening nobody made, and one made on a side branch is reported at the merge that carried it in. I will itemise the rest on request.
   • (a) The dashboard's --sync takes an optional directory: with one, it writes only that project; without one, every project it finds. It skips a target that git tracks, or a brand-new file the project's .gitignore does not cover, unless --force is given. Your pull request fix(dashboard): proportionate stale-copy remedy; bare --dry-run no longer writes (#67) #73 made the stale-copy warning say cp <canonical> <copy>; this branch's warning says --sync <directory> instead. Both answer check_stale_version() advertises --sync, which writes 26 files across 25 sibling repos #67, which found that the old warning advised a --sync that rewrote 26 files across 25 repositories.
   • (b) "methodology" is no longer in EXCLUDE_DIRS, so a run of the dashboard over a directory of projects scores this repository too.
   • (c) How the dashboard recognises a project's installed copy of a framework tool is now one table, and the list of names (FRAMEWORK_INSTALLED_SOURCE) is derived from it; yours keeps the list and a separate signature table, with a test that they agree. The same 7 names are recognised either way, but the trimmer loses its signature fallback: a copy with no TRIM_VERSION line is no longer recognised. Every version of the trimmer in your history (17 commits, 1.5.0 to 1.8.2) has that line.
   • (d) Five new risk rows: two for a file past the limits I measured for an agent's file-read tool (256 KiB, past which the read is refused, and 25,000 tokens, past which it is cut short with a banner, counted at 2.27 bytes per token, the densest content measured); two for a file a session is told to read whole, a ledger or a backlog, when it is past that budget (with a lower severity if the project's own trimmer can archive it); and one that repeats the trimmer's own size trigger (192 KiB). The thresholds are my choices.
   • (e) Two of your tests are removed: test_stale_warning_leads_with_the_project_scoped_remedy, because (a) replaces the cp remedy it asserts, and test_every_framework_installed_source_name_has_a_signature, because (c) derives the list of names from the signature table, so the two cannot disagree. The other two tests of TestCliRemedyProportionality assert behaviour this branch keeps and are restored as you wrote them (9848b62).
3. In what order should this and feat(trim): SESSION_NOTES.md joins the ledger table; warn of an uncommitted front-matter edit (refs #93) #98 go? feat(trim): SESSION_NOTES.md joins the ledger table; warn of an uncommitted front-matter edit (refs #93) #98 (open) and this branch both rewrite starter-kit/methodology_trim.py and its tests. Against feat(trim): SESSION_NOTES.md joins the ledger table; warn of an uncommitted front-matter edit (refs #93) #98's current head (65990cd), git merge-tree reports conflicts in 3 files and 5 regions (the trimmer 3, its tests 1, .quality-gates.json 1); feat(close-out): print and lint the Phase 3G close-out report (canonical-only tool; copy it) #96 (open) conflicts in 2 files and 3 regions (.quality-gates.json 2, bin/tests.sh 1). This branch carries none of feat(trim): SESSION_NOTES.md joins the ledger table; warn of an uncommitted front-matter edit (refs #93) #98's three commits (SESSION_NOTES.md in the trimmer's ledger table; two messages and three exit-3 statements made true; a warning for an uncommitted front-matter edit): the trimmer here is your 1.8.2 with the layout changes on top. Both name the trimmer 1.9.0 for different changes (feat(trim): SESSION_NOTES.md joins the ledger table; warn of an uncommitted front-matter edit (refs #93) #98's first commit, and this branch's trimmer commit), so whichever lands second takes a later number. Please say whether I should wait for feat(trim): SESSION_NOTES.md joins the ledger table; warn of an uncommitted front-matter edit (refs #93) #98 and rebase on it, or whether you will take this first and I rebase feat(trim): SESSION_NOTES.md joins the ledger table; warn of an uncommitted front-matter edit (refs #93) #98 and feat(close-out): print and lint the Phase 3G close-out report (canonical-only tool; copy it) #96 on it. I have not resolved the conflicts.
4. Three smaller choices.
   • 6ce88cd drops a duplicated example command (84 B) from the runner (SESSION_RUNNER.md) so that it reads under its token ceiling. The same commit also re-records the runner's bytes-per-token ratio in .context-budget.json, as the note in that file asks when the file changes, which lets the runner grow 43 B more before the budget tool (context_budget.py) reports it over. That second change can be dropped on its own; the cut alone is enough to pass.
   • Ten commits remove references that only my fork can resolve, such as backlog and session codes in comments and messages: seven (e051462 to 8c37c28) and a tail of three (1477af2 to 47637be). Please tell me whether to keep these commits or drop them; if you drop them, the references stay in the code. A merge commit or a rebase keeps them as separate commits and a squash folds them in. The tail can be dropped alone; the seven only with 9848b62 rebased. They are not exhaustive: some references of that kind remain, and 27 of the 33 commits end with a (cherry picked from commit ...) line that names a commit only my fork has.
   • No CHANGELOG.md entry and no change to README.md or CLAUDE.md (which list the files) is included; the 33 commits were made without your pre-commit hook, which would require a ledger entry in each. Please say if you want one entry for the whole pull request. I have not changed the release version; release notes would be a separate pull request, as with docs(release): v4.2 — CLAUDE.md §Versioning and README What's New #92.

The sections below give the detail behind these four items and the evidence.

Size, what reaches a project, and what it costs

Size. The branch adds 18,367 lines and removes 1,098 (git diff --shortstat d50ce29 HEAD). Most of that never reaches a project. bin/sync writes 19 of the changed files into a project, with 2,540 lines added and 526 removed in all; 3 more changed files are the sources of seeds, which only a new project receives. The other 25 files, with 15,820 of the added lines (86%), stay in this repository: tests, tools that only this repository runs, and its gate configuration. The dashboard is counted twice in that total (as starter-kit/methodology_dashboard.py and as an identical copy in tools/). About 37% of the added lines (6,883, in fbcef39 and 1d93579) are earlier work of mine that is not about the directory (pr4-distribution.py prints the split, pr4b-facts.sh the 37%).

What it costs to use. A session must read two of the framework's files in full, SESSION_RUNNER.md and SAFEGUARDS.md. Together they are 244 bytes (0.35%) larger on this branch, about 90 tokens at the runner's measured 2.81 bytes per token. The programs a session runs (the dashboard, the trimmer's check, the budget tool) took no longer than upstream's: the same on a project of 3 commits, and on one of 517 the dashboard took 0.66 s against 0.92 s (pr4-cost.sh).

What the change does

• Paths. bin/sync writes a project that keeps the current layout (called legacy in the tools' --layout options) the same paths it writes today (measured below). bin/sync and bin/check-links take --layout (for bin/sync, auto is the default: it keeps the layout a project has, and gives an empty project the current layout); bin/status and every other tool read either layout. The manifest has a second table, NEW_LAYOUT, giving each file's place under methodology/; it is plain data, so bin/sync --source github (which clones the framework repository) can read it without running it.
• No tool guesses where the files are. tools/layout_resolver.py is a short block of code that decides a project's layout from where an anchor file sits. The default anchor is SESSION_RUNNER.md: at the root, the current layout; under methodology/, the new one; in both places, the tool refuses and names both. A tool that reads a ledger anchors on that ledger instead, and the ratchet and the budget tool on their configuration file, so a project that moved only the framework's files (--tier 1, below) is read correctly. For a file other than the anchor that exists in both places (for example a project's own product CHANGELOG.md), the tool reads the copy under methodology/ as the framework's and leaves the other alone, but only when the runner is under methodology/ and not at the root; otherwise it refuses. The block is copied into 10 tools and into the dashboard's identical copy, because the four tools a project receives (methodology_dashboard.py, methodology_trim.py, context_budget.py, quality_ratchet.py) are single files that import only the standard library; the six tools that stay in this repository carry the same block, so one test covers all 11. python3 tools/test_layout_resolver.py fails until all 11 copies equal tools/layout_resolver.py.
• Moving a project. bin/migrate-layout makes no change unless given --apply. --tier 1 moves the framework's files, --tier 2 the project's own state (its seed files, the files the tools generate, the archive shards the trimmer wrote, and the project-owned PROJECT_LEARNINGS.md that BOOTSTRAP.md names), all (the default) both.
  • It refuses, before writing anything, a tree that is not a git repository with a commit; has uncommitted changes; is half-migrated (a runner at the root and another under methodology/); already holds a destination file; keeps its framework files out of git (its .gitignore lists them); is not current with what bin/sync would write; or has a file to rewrite that it cannot rewrite safely (for example, a ledger with a code fence that never closes).
  • An apply is one commit. It moves the files, rewrites the moved paths in CLAUDE.md, in anchored .gitignore entries and in .context-budget.json and .quality-gates.json, and adds a ledger entry. Every move must remain a rename at 90% similarity or better, so that git log --follow still reaches the history; a ledger too small for that fails (a project with a very short ledger must add entries first), and the apply is rolled back (exit 3), as is any step that fails before the commit. The report names git revert <commit> as the way back.
  • It checks itself. Before and after the commit it runs read-only checks (bin/status, the two ledger checkers, bin/check-links, every archive shard's proof, and how far git log --follow reaches). If a result differs afterwards, it exits 4 and keeps the commit (--skip-checks turns the checks off).
  • Like bin/sync and bin/status, it is not in bin/_manifest.py; a project runs it from a checkout of this repository. Its own suite of 280 tests takes about 6 minutes (two fast classes of it also run in bin/tests.sh), so the two gates that run it each set timeout_seconds to 3600.

What the commits contain

Each commit's message describes it. A suggested order for reading: fbcef39, then 41a1e58 (the foundation: the layout resolver, test projects in both layouts, bin/check-layout-literals, which finds a tool that names a file by its root path, and NEW_LAYOUT), then the rest in order. Of the last twelve commits, ten drop references that only my fork can resolve (decision 4); fd43f70 corrects four stale statements in comments and gate reasons, and 9848b62 restores the two tests named in decision 2 (e) and raises their gate's floor by two (neither changes a code path).

• fbcef39 (6 files, +6,187 / -552), earlier work. The dashboard 2.11.3 to 2.21.0 (both copies) and its tests. In bin/tests.sh: three blocks changed so that cmd | grep -q under pipefail cannot report a match as a failure, a lint for that pattern, a skip helper and an executable-bit check derived from the manifest. It also adds to BOOTSTRAP.md a row, in its table of files bin/sync never overwrites, that names every seed, and raises two thresholds in .quality-gates.json (the shell suite's, 261 to 271, and the dashboard's, 229 to 354). It fixes one defect: git log --reverse --format=%ai -1 applies -1 before it reverses, so first_commit_date was the newest commit and a project's age was the days since its last commit; the dashboard now reads the root commits (--max-parents=0).
• 1d93579 (4 files, +696 / -20), earlier work. The quality ratchet's 1.4.0 and 1.5.0. A gate may set timeout_seconds; a command that outlives it is reported unmeasured (its result could not be determined), not as exit code 127, and its whole process group is stopped. Two gates that read the same command's output share one run of it. Changing timeout_seconds is a warning, not a refusal. It does not depend on the layout, but it is built on the ratchet's layout commit 7d87cb2.
• d818ca1 (2 files, +5 / -2), a small change elsewhere. A rule in starter-kit/HANDOFFS.md and HOW_TO_USE.md for a close-out receipt that cites a gate run: a gate that read unmeasured must be repaired, or named in the receipt. Its check is in my version of bin/check-handoff, which is not carried, so the rule is prose only.
• One of your tests is rewritten (07ec025): Test 15 now counts the status table's rows, because bin/status prints a layout: line that names the project and the old assertion counted lines naming the project (31 for 30 files).
• 62680cd (5 files, +1,247 / -105), the trimmer. Your 1.8.2 with the layout changes on top, named 1.9.0: it finds a ledger at the root or under methodology/, writes its archive piece beside it and proves the trim. Its tests go from 227 to 265, and some of them compare against a frozen copy of the proof template 1.8.2 writes (tools/fixtures/trim-verify-template-1.8.2.sh, 483 lines).
• The dashboard is a whole file, not hunks, because my version had diverged from yours: a three-way merge of your copy with mine, from the copy my work began with (c8b9ddd), conflicts in 17 places in each of its two copies (pr4-mergefile.sh, with my fork's main as of e7b389f). The trimmer is not (the same merge conflicts in 1 place there and 1 in its tests). For bin/check-ledger and bin/check-handoff it contains the layout hunks only.

What a project sees

A project that keeps the current layout gets the same paths. Sync two temporary test projects, one with upstream's bin/sync and one with this branch's, and compare:

git init a-up && git -C a-up commit --allow-empty -m init ; cp -R a-up a-pr
python3 <upstream checkout>/bin/sync a-up ; python3 <this branch>/bin/sync a-pr
diff -rq --exclude=.git a-up a-pr

Both write the same 30 paths and neither makes a methodology/ directory. 22 of the 30 differ in bytes, and every one is a file this pull request changes: the cost of the next sync to a project that did not ask for the change. With its 7 seeds edited and its framework files at upstream's tip, upstream's bin/sync writes 0 paths; this branch's writes 19, needs no --force, and changes 0 of the 7 seeds (pr4-fixture.sh).

A project that has moved is synced where its files are. Take a project whose 30 files are already under methodology/. Upstream's bin/sync writes 30 paths outside methodology/, a second copy of every framework file and seed; this branch's writes none (pr4-moved.sh). So once a project can move, the sync tools have to change with it. On my 7 projects that had moved, upstream's bin/sync wrote 23 framework files at the old places at each and created 41 seed files at the root across six of them; two projects' own pre-commit hooks refused the resulting commit as half-migrated.

My own 12 projects (7 under methodology/, 5 not; pr3b-adopters.py is the method) are mine, so you cannot run this on them. Without --force, this branch's bin/sync refuses 10 of them, over 52 files: 51 are versions from my fork's history that no commit of this branch carries, and one is a project's own edit of methodology_trim.py (49 lines differ from my fork's copy), which --force drops without saying so. After one --force, a plain run writes nothing at any of the 12; it changed none of their seeds.

Evidence

Each check ran in a fresh --no-local clone of the head with no modified files, serially; upstream's tip is the control. pr4b-claims.sh runs them all (about 30 minutes).

Check	Command	upstream d50ce29	this branch
The suite passes and has more tests	bash bin/tests.sh	261 passed, 0 failed	302 passed, 0 failed, 0 skipped
Every declared gate holds	python3 starter-kit/quality_ratchet.py --run	12/12 pass, 0 fail, 0 unmeasured	18/18 pass, 0 fail, 0 unmeasured
Links resolve in both layouts	python3 bin/check-links --layout both	usage error: it takes only --tree (exit 2)	OK: 80 links across 23 documents, in each layout (116 at your tip)
One copy of the layout-deciding code	python3 tools/test_layout_resolver.py	not present	76 tests OK; 11 copies, each equal to tools/layout_resolver.py
No gate threshold in .quality-gates.json is lowered	quality_ratchet.compare, each commit against its parent		0 refusals over 33 commits; gates 12 to 18; five thresholds raised

I ran the suite and the gates at points through the series, not at every commit.

What this does not show, and what is missing

• The route a project takes alone from GitHub: every sync above used the local source, not bin/sync --source github.
• Any project that is not mine: the 12 are mine, and 10 carry versions of the framework's files that are in no history here.
• Windows, your machine, a project's own CI: this repository has no CI, so every check is local.

Known gaps

These came from the 12 projects and are open:

• A sync refuses a project's edited framework file by name but does not say which published version is nearest or how many lines differ, and --force then drops the edit (upstream's bin/sync does the same).
• With only the framework's files moved (--tier 1), the dashboard writes a second history file, dashboard_history.jsonl, under methodology/ while the one at the root stays, unused.
• On a ledger in the old format (no month headings), the migration appends its entry at the end, out of order; bin/check-ledger fails on such a ledger before and after.
• For the hook that context_budget.py install-hook writes, the migration warns that it "will refuse the migration commit". In fact the hook does not refuse it.
• An earlier copy of the ledger pre-commit hook of SAFEGUARDS.md keeps looking for the ledger at the root, so once the ledger moves it passes a commit with no ledger entry, without saying so. The migration reports such a hook and leaves it. The hook in this branch (.githooks/pre-commit) follows the ledger.
• A project's own tests or scripts that read a moved file by name can break. The migration lists the other files whose text mentions a moved name; the list is an upper bound, not the set that breaks.

🤖 Generated with Claude Code