Skip to content

fix(trusty-mpm): retire .trusty-mpm/ overrides; remove the framework floor (#4286) - #4665

Merged
bobmatnyc merged 3 commits into
mainfrom
fix/4286-claude-md-canonical-overrides
Aug 3, 2026
Merged

fix(trusty-mpm): retire .trusty-mpm/ overrides; remove the framework floor (#4286)#4665
bobmatnyc merged 3 commits into
mainfrom
fix/4286-claude-md-canonical-overrides

Conversation

@bobmatnyc

@bobmatnyc bobmatnyc commented Aug 3, 2026 •
edited
Loading

Copy link
Copy Markdown
Owner

Refs #4286. Two rulings, in order: CLAUDE.md named sections become the sole project override surface, and the non-overridable framework floor is removed entirely.

Part 1 — hard cut on the five .trusty-mpm/ files

Chosen over read-with-deprecation because the ruling calls the additive read a bug, and read-with-deprecation would leave .trusty-mpm/INSTRUCTIONS.md half-alive. A leftover file gets two signals sharing one detector: tracing::error! from the resolver on every launch, and a tm doctor check legacy_overrides that FAILS and names the migration.

Measured blast radius: 52 file instances on this machine, all INSTRUCTIONS.md, deduplicating to 4 distinct projects. Zero instances of the other four files. Zero of the 52 contain a TRUSTY-MPM: marker — which is what made dropping the second marker host safe.

Part 2 — the framework floor is gone

SectionId::is_floor(), FloorNotFixed, OverridableAfterFloor, validate_floor_is_last, check_instruction_floor.sh, instruction_floor.sha256, the guard workflow, and its duplicated ci.yml step. Grepped for callers before deleting; the one survivor was a prose mention in check_generation_artifacts.sh, corrected.

core is now the only fixed section. validate enforces this as an iff, so marking a second section fixed — how a floor creeps back — is a hard error.

No content moved between sections. core.md byte delta from this restructure: 0. Compiled prompt net change vs origin/main: +763 bytes, entirely the do-not-embellish rule and the retirement/tier prose.

Accepted consequence, recorded not worked around

The prohibitions, attribution footer, tool-priority mandate, and never turn red green by deleting coverage are now overridable. The README says so plainly, including that promoting them into core.md was considered and rejected.

Acceptance test against a real tm instance

Run with the branch binary (target/debug/tm), not the installed 1.3.2, against a scratch project. All four PASS:

# Assertion Result
1 Canonical path <PROJECT>/.trusty-mpm/last-instructions.md, the only file written
2 Matches sources all 9 sections present, exactly once, in manifest order
3 Dynamic roster 43 agents, reconciling exactly against the on-disk tier union (0 diff both directions)
4 CLAUDE.md reference present after the fix below

The defect this caught

Assertion 4 was a genuine gap — nothing referenced the compiled file, and the stub pointed at BASE_PM.md, deleted in #4183. Closing it introduced a worse bug that the real run then caught: a worked marker example in the stub parsed as a live WORKFLOW override, so every newly seeded project silently lost its entire bundled workflow section and received placeholder prose. Marker recognition is whole-line and ignores code fences.

Observed before the fix: bundled workflow heading count 0, placeholder text present in the delivered prompt. No unit test or golden could have caught this — none exercise the seeded stub. Guarded now by seeded_claude_md_declares_no_overrides.

Tests: inverted, not deleted

One gate per retired file asserts the file changes nothing. The #4399 cluster and the floor tests were removed only because their preconditions are now unconstructible, each replaced by a direct proof. The #4573 gate is inverted: the three-line CORE attack is now refused outright rather than survived.

Gates

Gate Result
cargo test -p trusty-mpm 4289 passed; 0 failed; 7 ignored (all targets green)
cargo clippy -p trusty-mpm --all-targets -- -D warnings exit 0
cargo fmt -p trusty-mpm --check exit 0
check_line_cap.sh / check_sld.sh / check_doc_numbers.sh / check_generation_artifacts.sh PASS

Goldens regenerated; diff is 4 hunks, each traceable to an intended edit.

Open findings (in the README, not fixed here)

  1. Two writers target ~/.trusty-mpm/framework/instructions/INSTRUCTIONS.md.
  2. base_pm() is a misnomer twice over — renaming left out to keep this reviewable.
  3. project-addendum is declared but unfeedable.

Deliberately NOT in this PR

trusty-tools' own .trusty-mpm/INSTRUCTIONS.md migration; the bundled assets/instructions/INSTRUCTIONS.md retirement; the shipped-asset text sweep.

🤖🤖🤖 Generated with trusty-mpm — https://github.com/bobmatnyc/trusty-tools

@bob-duetto
fix(trusty-mpm): retire the five .trusty-mpm/ instruction override files
3e89f15 
CLAUDE.md named sections become the sole project customization surface.
The five `.trusty-mpm/` override files are no longer read at all, and
`.trusty-mpm/INSTRUCTIONS.md` stops being a marker host — `CLAUDE.md` is
the only one.

Hard cut, not read-with-deprecation: the owner ruling calls the additive
read a bug, and a half-alive file (honoured for markers, ignored for
prose) is the ambiguous state the retirement exists to remove.

A silent cut was unacceptable, so a leftover file gets two loud signals:
`tracing::error!` from the resolver on every launch, and a new `tm doctor`
check `legacy_overrides` that FAILS and names the migration. Both share
one detector so they cannot disagree.

Enumerated blast radius first: 52 file instances on this machine, all
`INSTRUCTIONS.md`, across 4 distinct projects (the rest are worktree
checkouts of the same tracked file). Zero instances of the other four
files anywhere. Zero of the 52 contain a `TRUSTY-MPM:` marker, so
dropping the second marker host costs no project an override.

Tests are inverted rather than deleted: one gate per retired file now
asserts the file changes nothing. The #4399 non-shadowing cluster is
removed because its precondition (a legacy file forcing the string
assembly) is unconstructible once nothing is read — replaced by a direct
proof that all five files present leave the prompt byte-identical.

Floor: `non-overridable-rules` said the files were "still read by the
current binary". One pinned digest regenerated for that section.
`core.md` (tier project, unpinned) gains the do-not-embellish rule.

Adds `sections/README.md` documenting composition, tiers, the pinned
floor, and what must not come back.

Refs #4286

🤖🤖🤖 Generated with trusty-mpm — https://github.com/bobmatnyc/trusty-tools
@bobmatnyc bobmatnyc added this to the tm 1.3.3 milestone Aug 3, 2026
@bobmatnyc bobmatnyc added trusty-mpm trusty-mpm platform and related work ws/tm-dogfood-relaunch-01 trusty-mpm workstream tm-dogfood-relaunch-01 labels Aug 3, 2026
@bobmatnyc bobmatnyc self-assigned this Aug 3, 2026
@bob-duetto
refactor(trusty-mpm): remove the framework floor; core is the only pr…
625f334 
…otected section

Owner ruling: a project owns its own CLAUDE.md, so a non-overridable floor
bought the appearance of a control rather than a control. Remove the whole
mechanism and make `core` the single section a named-section override
cannot replace.

Removed: SectionId::is_floor(), the FloorNotFixed and OverridableAfterFloor
validation rules, validate_floor_is_last, check_instruction_floor.sh,
instruction_floor.sha256, the instruction-floor-guard workflow, and its
duplicated step in ci.yml. Grepped for callers first (#4660 discipline); the
only survivor was a prose mention in check_generation_artifacts.sh, corrected.

NO CONTENT MOVED between sections. identity, enforcement,
non-overridable-rules and framework-guaranteed-conventions keep their text
and simply become tier `project`. core.md is byte-identical to the previous
commit (delta 0). `validate` now enforces the tier assignment as an iff, so
both retiering core away from `fixed` and marking a second section `fixed`
are hard errors — the latter is how a floor would creep back.

Accepted consequence, recorded in the README rather than worked around: the
prohibitions, attribution footer, tool-priority mandate, and
never-turn-red-green are now overridable. Promoting them into core.md would
defeat the point of removing the mechanism.

Acceptance testing against a REAL tm instance (branch binary, not the
installed 1.3.2) found a defect no unit test or golden could: a worked
marker example in the seeded CLAUDE.md stub parsed as a LIVE WORKFLOW
override, so every newly seeded project silently lost its bundled workflow
section. Marker recognition is whole-line and ignores code fences. Fixed by
showing the markers inline, guarded by seeded_claude_md_declares_no_overrides.

The stub also now points at .trusty-mpm/last-instructions.md and no longer
refers to BASE_PM.md, which has not existed since #4183.

Refs #4286

🤖🤖🤖 Generated with trusty-mpm — https://github.com/bobmatnyc/trusty-tools
@bobmatnyc bobmatnyc changed the title fix(trusty-mpm): retire the five .trusty-mpm/ instruction override files (#4286) fix(trusty-mpm): retire .trusty-mpm/ overrides; remove the framework floor (#4286) Aug 3, 2026
@bob-duetto
fix(trusty-mpm): repoint dangling test pointers, regenerate tm-capabi…
99ab7ae 
…lities

Two CI checks I did not run locally were red. Both are fallout from the
#4286 retirement.

1. Doc-comment pointer lint: 16 pointers cited test names removed or
   renamed by the retirement. Each was repointed at the test that now
   covers the behaviour, not deleted to silence the lint.

   Two of them named behaviours that STILL EXIST but had lost their only
   coverage when the retired-file tests went:

   - `MEMORY_OVERRIDE_HEADING` slotting — still live in `assemble_sections`,
     reachable via a CLAUDE.md MEMORY block on the roster-absent path.
   - `warn_unapplied` for sections the string assembly cannot address —
     still called; its test went with the #4399 cluster.

   Deleting those two pointers would have hidden untested live behaviour,
   so coverage was restored first:
   `a_named_memory_override_is_slotted_on_the_roster_absent_path` and
   `unaddressable_sections_are_reported_unapplied_on_the_roster_absent_path`.

2. tm-capabilities drift: the new `legacy_overrides` doctor check was not
   reflected. Regenerated with `tm generate capabilities`; verified the
   output actually carries the check (position 15, count 28 -> 29) rather
   than assuming.

Adding the two tests took `instruction_overrides.rs` to 538 SLOC, over the
500 production cap, so its inline test module is extracted to
`instruction_overrides_tests.rs` via `#[path]` — the same split
`claude_md_sections.rs` already uses.

Refs #4286

🤖🤖🤖 Generated with trusty-mpm — https://github.com/bobmatnyc/trusty-tools
@bobmatnyc
bobmatnyc merged commit 7d4a859 into main Aug 3, 2026
26 checks passed
This was referenced Aug 3, 2026
Merged
Merged
bobmatnyc added a commit that referenced this pull request Aug 3, 2026
@bobmatnyc
fix(trusty-mpm): retire the bundled instructions/INSTRUCTIONS.md stub…
ca58540 
… asset (#4673)

Split A of the #4286 retirement (splits B and C land separately). This is
the framework-owned bundled artifact
(crates/trusty-mpm/src/assets/instructions/INSTRUCTIONS.md, embedded as
FRAMEWORK_INSTRUCTIONS and installed to instructions/INSTRUCTIONS.md),
distinct from the project-level .trusty-mpm/INSTRUCTIONS.md override file
already retired by #4665.

Its content never reached a live session: tm install/tm launch always
overwrite that same on-disk path with the fully assembled system prompt
(assemble_system_prompt) in the same call, and the one legacy reader
that still touches it (build_instructions) already discards the result
for anything beyond a CLAUDE.md-seeding side effect. Removing it changes
nothing observable — verified byte-identical before/after on both the
installed framework file and the per-project composed prompt.

Removes the asset file, the FRAMEWORK_INSTRUCTIONS constant, its bundle
table entry, and the now-orphaned framework_instructions_overwrites test
(the artifact it asserted on no longer exists).

Refs #4286
bobmatnyc added a commit that referenced this pull request Aug 3, 2026
@bobmatnyc @bob-duetto
fix(trusty-mpm): sweep shipped asset text advertising retired .trusty…
6276ec2 
…-mpm/ overrides (#4672)

PR #4665 retired the five project-level .trusty-mpm/ PM instruction
override files, but shipped asset text still told users and the PM to
create and use them. Rewrite the tm-workflow skill, three output
styles, and three cross-referencing skills to describe the current
model: framework instructions compose from
assets/instructions/sections/*.md, and CLAUDE.md named-section
markers are the sole project-customization channel.

sections/workflow.md's test-ladder pointer was also stale and feeds
the compiled prompt directly, so the pm-prompt-bundled-fallback.md and
pm-prompt-roster-absent.md golden fixtures are regenerated to match.
Regenerated tm-capabilities (skills.md) for the tm-workflow
description change.

Verified no scaffolding path (tm-init, tm project init) creates any of
the five retired files.

Refs #4286

Co-authored-by: Bob Matsuoka <robert.matsuoka@duettoresearch.com>
This was referenced Aug 3, 2026
Merged
Merged
bobmatnyc added a commit that referenced this pull request Aug 3, 2026
@bobmatnyc
docs(specs): drop retired instruction-floor-guard.yml from DOC-62's g…
11b02f8 
…ate list

The workflow was deleted by #4665 (framework-floor retirement), so listing it
alongside currently-enforced gates overstated it as live. This is a
pre-existing defect the PR's status bump to Accepted gives more apparent
authority to; fixing here rather than filing a follow-up.

The other two citations the review flagged (lines 163, 805 — the delivery-
chain source) already point at CLAUDE.md, not the retired
.trusty-mpm/INSTRUCTIONS.md: commit 2e8a36b (#4676), already an ancestor of
this branch, fixed both before this review ran. Verified by grep — no
remaining .trusty-mpm/INSTRUCTIONS.md or other stale-mechanism references in
either DOC-62 or DOC-63.

Addresses the HIGH finding on PR #4677:
#4677 (comment)

🤖🤖🤖 Generated with trusty-mpm — https://github.com/bobmatnyc/trusty-tools
This was referenced Aug 3, 2026
Closed
Merged
bobmatnyc added a commit that referenced this pull request Aug 3, 2026
@bobmatnyc
docs(specs): drop retired instruction-floor-guard.yml from DOC-62's g…
a0fbb1c 
…ate list (#4689)

The workflow was deleted by #4665 (framework-floor retirement), so listing it
alongside currently-enforced gates overstated it as live. This is a
pre-existing defect the PR's status bump to Accepted gives more apparent
authority to; fixing here rather than filing a follow-up.

The other two citations the review flagged (lines 163, 805 — the delivery-
chain source) already point at CLAUDE.md, not the retired
.trusty-mpm/INSTRUCTIONS.md: commit 2e8a36b (#4676), already an ancestor of
this branch, fixed both before this review ran. Verified by grep — no
remaining .trusty-mpm/INSTRUCTIONS.md or other stale-mechanism references in
either DOC-62 or DOC-63.

Addresses the HIGH finding on PR #4677:
#4677 (comment)

🤖🤖🤖 Generated with trusty-mpm — https://github.com/bobmatnyc/trusty-tools
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

@bobmatnyc bobmatnyc

Labels

trusty-mpm trusty-mpm platform and related work ws/tm-dogfood-relaunch-01 trusty-mpm workstream tm-dogfood-relaunch-01

Projects

None yet

Milestone

tm 1.3.3

Development

Successfully merging this pull request may close these issues.

2 participants

@bobmatnyc @bob-duetto