Clean Motus local workspace and source-of-truth friction

[bnvoss]

Parent

Cross-repo roadmap item tracked in motus-os/motus-work-ledger#41.

Problem

Repeated GitHub/process friction was not only a GitHub issue. The local Motus workspace had multiple stale source-of-truth signals that could cause agents to use old branches, old remotes, old process docs, or an old installed Motus CLI.

Current verified state on 2026-05-22

• Bare motus now resolves to motusos 0.5.3; the stale global 0.3.5 install has been remediated.
• Current canonical /motus source worktree is /Users/ben/GitHub/worktrees/motus-cr-motus-0.4.6-store-first-work-truth-1-20260508.
• That canonical worktree is clean on main and matches origin/main.
• /Users/ben/GitHub/motus is still a stale CR checkout on cr-motus-release-workflow-actions-parity-1-20260504, ahead 1 / behind 45 against public/main; it should not be treated as canonical source.
• Dead local remote hardening has been removed.
• Remaining registered /motus worktrees include many historical branches; dirty or unmerged worktrees must not be deleted without targeted review.
• Supporting generic cache/session cleanup is complete in motus-internal; remaining work here is source-of-truth/worktree hygiene only.

Scope

Inventory and clean the local Motus workspace process hazards without deleting user work or unreviewed state.

Acceptance criteria

• Inventory active vs stale Motus worktrees and branches.
• Archive or remove only clean, merged, or explicitly obsolete worktrees after verification.
• Define the canonical local checkout/worktree for /motus work.
• Define authoritative remote names for public and internal work.
• Ensure current Motus CLI invocation is deterministic for Work Journal usage.
• Preserve all unmerged or user-authored work.
• Link evidence back to Cross-repo roadmap: Work Journal operating loop and repo hygiene motus-work-ledger#41 and the relevant Work Journal run/receipt.

Non-goals

• Do not rewrite Git history.
• Do not delete unknown dirty worktrees.
• Do not change product code unless a separate issue/claim covers it.

[bnvoss]

Local cleanup pass completed and linked to the cross-repo roadmap.

Result on 2026-05-21:

• Free space improved to about 107 GiB.
• /Users/ben/.codex dropped from about 123G to about 40G.
• /Users/ben/.codex/sessions dropped from about 118G to about 38G.
• Deleted Codex sessions older than 30 days, Codex backup sessions, oversized Codex TUI log, npm cache, and Playwright/browser caches.
• Did not delete /Users/ben/GitHub/worktrees yet; that remains about 29G and requires dirty/unmerged worktree review before removal.

Internal operating-model implementation for retention policy is tracked at motus-os/motus-internal#896.
Cross-repo roadmap parent is motus-os/motus-work-ledger#41.

[bnvoss]

Non-destructive inventory update - 2026-05-21

I inventoried registered /motus worktrees and did not delete anything.

Report paths:

• /tmp/motus-worktree-list-20260521.porcelain
• /tmp/motus-worktree-inventory-20260521.tsv

Findings:

• Registered /motus worktrees: 44
• Clean: 41
• Dirty: 3
• Unknown: 0
• Total registered /motus worktree footprint: about 0.8 GiB

Important correction:
The broader /Users/ben/GitHub/worktrees directory is about 29G, but that is not all /motus. It includes other repo worktrees, especially website/internal worktrees. Broad worktree pruning should be handled by motus-os/motus-internal#896. This /motus issue should stay focused on source-of-truth friction: canonical checkout, stale main ownership, remote names, and PATH resolving to old motus.

No deletion was performed.

[bnvoss]

Execution recap: /motus source-of-truth inventory for MOTUS-137

Confidence before step: 88%. Confidence after verification: 94%.

Verified facts:

• Canonical current /motus source worktree is /Users/ben/GitHub/worktrees/motus-cr-motus-0.4.6-store-first-work-truth-1-20260508.
• That worktree is clean on main and exactly equals origin/main@0d8177b92bf3ac8ad20cc31031112e2462ce544e.
• Source-bound command reports motus 0.5.3: PYTHONPATH=/Users/ben/GitHub/worktrees/motus-cr-motus-0.4.6-store-first-work-truth-1-20260508/packages/cli/src python3 -m motus.cli --version.
• Source-bound doctor --json passes against the Work Ledger project Store at /Users/ben/GitHub/motus-work-ledger/.motus/kernel-store.db.
• Global PATH still resolves motus to /Library/Frameworks/Python.framework/Versions/3.10/bin/motus, which reports motus 0.3.5; that is the likely root cause of recurring old-process behavior when commands are not source-bound.
• /Users/ben/GitHub/motus is not current main; it is on cr-motus-release-workflow-actions-parity-1-20260504, clean, but ahead 1 / behind 45 against public/main. Treat it as a stale CR checkout, not canonical source.
• Worktree inventory captured at /tmp/motus-137-worktree-status-20260521.tsv; one dirty registered /motus worktree was identified: /Users/ben/GitHub/worktrees/motus-0.5.0-release-audit-20260512. No deletion performed.
• hardening remote points at missing /tmp/motus-hardening; recommend removing or documenting in a separate cleanup step.
• public duplicates origin via SSH; recommend keeping origin authoritative and only retaining public if explicitly documented as an alias.

Current deterministic command rule for ongoing work:

PYTHONPATH=/Users/ben/GitHub/worktrees/motus-cr-motus-0.4.6-store-first-work-truth-1-20260508/packages/cli/src python3 -m motus.cli <command>

Work Journal evidence recorded on active run run_01779391662570449000_f576dce45130, lease lease-2eacb5bb0ed0, evidence evidence-41c04898c91b.

Recommended next actions:

1. Stop using bare motus until PATH is updated or explicitly pinned.
2. Document the canonical source-bound command in repo-local operator notes.
3. Run branch/worktree hygiene separately; do not delete the dirty worktree automatically.
4. Remove or document the missing hardening remote after explicit cleanup approval.

[bnvoss]

Follow-up cleanup under MOTUS-137

Confidence before cleanup: 94%. Confidence after cleanup: 96%.

Action taken:

• Removed dead local remote hardening from the /motus gitdir.

Evidence:

• Before removal, hardening pointed to /tmp/motus-hardening for fetch and push.
• /tmp/motus-hardening does not exist.
• After removal, remotes are:
  • origin -> https://github.com/motus-os/motus.git
  • public -> git@github.com:motus-os/motus.git

Work Journal evidence recorded on run run_01779391985991699000_617e55ba7347, lease lease-b5dca5ccfb4e, evidence evidence-925b868c8623.

No worktrees or branches were deleted. The remaining source-of-truth risk is the stale global PATH motus 0.3.5; recommended next control is to document or update command resolution so Work Journal operations are source-bound to current /motus until PATH cleanup is deliberate.

[bnvoss]

Cross-repo hygiene update - 2026-05-21

The supporting motus-internal local generated artifact retention lane is complete.

Completed:

• motus-os/motus-internal#896 closed.
• motus-os/motus-internal#897 merged at d1f623ad4cfb06b754065626b89f93e1e06f0271.
• Follow-up review blocker fixed: cleanup apply mode protects the report path if --report is under a deletable tree.
• Clean merged PR worktree /Users/ben/GitHub/worktrees/motus-internal-local-retention-20260521 removed and local branch deleted.

Work Journal receipts:

• PR merge closeout: sha256:447545c07cd2021613283e2567d80a5a44bb427760de27ef13a6ef22677e463a
• Local worktree cleanup: sha256:bf461e6e1fcac56f05cf8565e13abc6ccc4d693cdae97f4f2977573fe5adc7c6

Impact on this issue:

• Generic cache/session cleanup is no longer blocking; it has an owned repeatable path in motus-internal.
• Remaining /motus source-of-truth work is narrower: stale global PATH resolving motus 0.3.5, canonical current source-bound command, and branch/worktree cleanup only after dirty/unmerged review.
• No additional /motus worktrees were deleted in this closeout.

[bnvoss]

PATH inventory update - 2026-05-21

Work Journal run: run_01779395347134359000_8e886fe91285

Confirmed non-destructively:

• which -a motus returns only /Library/Frameworks/Python.framework/Versions/3.10/bin/motus.
• motus --version reports motus 0.3.5 (Apache 2.0).
• The console script imports from motus.cli.core import main under /Library/Frameworks/Python.framework/Versions/3.10/bin/python3.
• /Library/Frameworks/Python.framework/Versions/3.10/bin/python3 -m pip show motusos reports motusos 0.3.5 at /Library/Frameworks/Python.framework/Versions/3.10/lib/python3.10/site-packages.
• python3 -m pip show motusos resolves the same installation.

Root cause class:

• Bare motus is pinned to an old global Python install, so agents that use bare motus can silently execute the old 0.3.5 process even while current /motus source-bound commands are 0.5.3.

Decision:

• No global uninstall/upgrade was performed in this pass. Changing the system Python framework package is reversible but still broad enough to require a deliberate remediation choice.

Current safe command remains:

PYTHONPATH=/Users/ben/GitHub/worktrees/motus-cr-motus-0.4.6-store-first-work-truth-1-20260508/packages/cli/src \
MOTUS_KERNEL_STORE_PATH=/Users/ben/GitHub/motus-work-ledger/.motus/kernel-store.db \
python3 -m motus.cli <command>

Recommended remediation options, in order of safety:

1. Create a repo-local helper/alias that always source-binds to current /motus for agent use.
2. Install/update motusos==0.5.3 in a dedicated virtualenv and put that shim ahead of the Python 3.10 framework path.
3. Only after confirming nothing depends on global 0.3.5, upgrade or uninstall the global framework package.

[bnvoss]

PATH remediation update - 2026-05-21

Work Journal run: run_01779402435462037000_5608e2bfdaec
Lease: lease-327da87c0c24

Completed:

• Upgraded the Python framework installation that owns the bare motus console script from motusos 0.3.5 to motusos 0.5.3.
• Verified a fresh login shell now resolves motus to /Library/Frameworks/Python.framework/Versions/3.10/bin/motus and motus --version reports motus 0.5.3 (Apache 2.0).
• Verified the installed package summary is now Store-first: Local event-backed work ledger with Store runs, append-only events, receipts, and projections.
• Updated /Users/ben/AGENTS.md with a local command-resolution rule: cross-repo Work Journal activity must use the shared Store via MOTUS_KERNEL_STORE_PATH=/Users/ben/GitHub/motus-work-ledger/.motus/kernel-store.db motus ...; default runtime tests should explicitly unset MOTUS_KERNEL_STORE_PATH.
• Verified the shared Store command works: MOTUS_KERNEL_STORE_PATH=... motus work list --json sees the active remediation lease.
• Verified default runtime behavior remains clean when MOTUS_KERNEL_STORE_PATH is unset: motus doctor --json and python3 -c 'import motus.config' created no HOME state and no project .motus in a fresh test HOME/project.

Impact:

• The old-process root cause is closed for bare motus: agents should no longer silently run motusos 0.3.5.
• Cross-repo Work Journal consistency is now explicit in the operator instructions without globally exporting MOTUS_KERNEL_STORE_PATH, which avoids contaminating package/runtime truth tests.

Remaining items on this broader issue:

• Dirty/unmerged worktree cleanup remains intentionally non-destructive.
• /Users/ben/GitHub/motus remains a stale CR checkout and should not be treated as canonical main.
• Canonical current source worktree remains /Users/ben/GitHub/worktrees/motus-cr-motus-0.4.6-store-first-work-truth-1-20260508.

[bnvoss]

Fresh worktree inventory - 2026-05-22

Work Journal run: run_01779458958689525000_599f9162f350
Lease: lease-c4feb487f9c9

Inventory file:

• /tmp/motus-137-worktree-status-20260522.tsv

Summary:

• Registered worktree rows including header: 45.
• Clean worktrees: 43.
• Dirty worktrees: 1.
• Canonical current worktree: /Users/ben/GitHub/worktrees/motus-cr-motus-0.4.6-store-first-work-truth-1-20260508 on main, clean, upstream parity 0/0.
• Dirty worktree: /Users/ben/GitHub/worktrees/motus-0.5.0-release-audit-20260512 on cr-motus-0.5.0-stable-kernel-release-execution-1-20260512-public, no upstream. Do not delete automatically.
• Root checkout /Users/ben/GitHub/motus remains clean but stale: cr-motus-release-workflow-actions-parity-1-20260504, ahead/behind 1/45 against public/main.
• Many clean historical worktrees have no upstream. They are cleanup candidates only after branch-aware review confirms the local branch can be preserved or removed safely.

Decision:
No worktrees were deleted in this pass. The next safe action is branch-aware classification of clean no-upstream worktrees into preserve/archive/remove candidates. Dirty worktree deletion remains a stop condition.

[bnvoss]

Superseded by the corrected cleanup record in #137 (comment). The original comment body was malformed by local shell interpolation around backticked /motus text during posting.

[bnvoss]

Correction to prior cleanup comment - 2026-05-22

The immediately preceding comment was posted with shell-interpreted backticks around /motus, which caused local zsh command-substitution warnings before posting. This comment is the authoritative clean record for the batch.

Work Journal run: run_01779459258939515000_d3bb258e0a16
Lease: lease-2cfd8477463d

Classification file:

• /tmp/motus-137-worktree-classification-20260522.tsv

Action taken:

• Removed 28 clean /motus worktrees whose HEAD was already an ancestor of origin/main.
• Preserved the canonical current main worktree: /Users/ben/GitHub/worktrees/motus-cr-motus-0.4.6-store-first-work-truth-1-20260508.
• Preserved the dirty stop-condition worktree: /Users/ben/GitHub/worktrees/motus-0.5.0-release-audit-20260512.
• Preserved 14 clean but unmerged/no-upstream review candidates.

Post-cleanup verification:

• Post-cleanup inventory: /tmp/motus-137-worktree-post-cleanup-20260522.tsv.
• Registered /motus worktree rows including header: 17.
• Clean non-canonical worktrees remaining: 14 plus the stale root checkout.
• Dirty worktrees remaining: 1.
• Canonical main worktree remains clean on main...origin/main.
• Overall /Users/ben/GitHub/worktrees remains about 29G, confirming most remaining space is from other repos/worktrees, not registered /motus worktrees.

Decision:
No dirty worktree or unmerged clean worktree was deleted. Next safe step is branch-aware review of the remaining clean/unmerged candidates and a separate broader worktree inventory outside /motus if disk pressure remains.

[bnvoss]

Final high-confidence worktree cleanup pass - 2026-05-22

Work Journal run: run_01779459568940645000_69894f52d4f1
Lease: lease-b3496f8f4fc1

Classification file:

• /tmp/motus-137-unmerged-worktree-review-20260522.tsv

Action taken:

• Reviewed the remaining clean non-canonical /motus worktrees for PR history.
• Each remaining clean non-root worktree mapped to a merged PR.
• Removed those clean non-root worktrees with merged PR history.
• Preserved local branches by removing worktrees only; no branch deletion was performed.

Final registered /motus worktree set:

• /Users/ben/GitHub/worktrees/motus-cr-motus-0.4.6-store-first-work-truth-1-20260508: canonical current main, clean.
• /Users/ben/GitHub/motus: stale root checkout, clean but ahead 1 / behind 45 against public/main; preserved for explicit root-checkout decision.
• /Users/ben/GitHub/worktrees/motus-0.5.0-release-audit-20260512: dirty release-audit worktree; preserved as stop condition.

Verification:

• Final inventory file: /tmp/motus-137-worktree-final-20260522.tsv.
• Canonical main remains clean on main...origin/main.
• Dirty worktree still has modifications in CHANGELOG, README, GitHub Actions docs, pyproject, and motus.__init__.
• Overall /Users/ben/GitHub/worktrees is still about 28G, so remaining disk pressure is mostly outside registered /motus worktrees.

Decision:
/motus#137 should stay open only for two explicit decisions:

1. what to do with stale root checkout /Users/ben/GitHub/motus, and
2. what to do with dirty release-audit worktree /Users/ben/GitHub/worktrees/motus-0.5.0-release-audit-20260512.

Do not delete either without direct review.

[bnvoss]

Preserved-state review - 2026-05-22

Work Journal run: run_01779462305551379000_04f9a3224bac
Lease: lease-a0a76413c760

Report:

• /tmp/motus-137-preserved-state-review-20260522.md

Stale root checkout

Path: /Users/ben/GitHub/motus

Findings:

• Branch: cr-motus-release-workflow-actions-parity-1-20260504.
• State: clean.
• Relation: ahead 1 / behind 45 against public/main.
• PR history: motus-os/motus#100, MERGED, ci: harden draft release workflow.
• Unique diff versus public/main: .github/workflows/release.yml, 63-line workflow hardening diff.

Decision:
Preserve for now. Safe next action is an explicit root-checkout decision: retire/rename it, or intentionally keep it as an archive. Do not reset it silently because /Users/ben/GitHub/motus may still be used by operator muscle memory or old scripts.

Dirty release-audit worktree

Path: /Users/ben/GitHub/worktrees/motus-0.5.0-release-audit-20260512

Findings:

• Branch: cr-motus-0.5.0-stable-kernel-release-execution-1-20260512-public.
• State: dirty.
• Dirty files: CHANGELOG.md, README.md, packages/cli/docs/github-actions.md, packages/cli/pyproject.toml, packages/cli/src/motus/__init__.py.
• Diff meaning: local 0.5.0 release-prep edits, including version bump from 0.4.14 to 0.5.0, GitHub Action examples to v0.5.0, and a 0.5.0 changelog entry.
• Current main truth: version is 0.5.3, GitHub Action examples use v0.5.3, and CHANGELOG already contains 0.5.3 and 0.5.0 entries.

Decision:
Likely obsolete release-prep scratch state, but still dirty user work. Do not delete or reset without explicit approval.

Current #137 status

High-confidence cleanup is complete. Remaining actions are explicit preservation decisions, not general cleanup:

1. decide whether to retire or keep /Users/ben/GitHub/motus, and
2. decide whether to archive or delete the dirty 0.5.0 release-audit worktree after human approval.