[self-repair:9ccc1cada326] [orchestrator-defect] self-update overwrites consumer guidance and restores project placeholders

[srnichols]

Class

orchestrator-defect

Symptom

In Rummag, self-update v3.26.5 to v3.26.7 replaced customized Git instructions (master and explicit path-limited commits) with generic main and git add -A; replaced marketplace security guidance with Plan Forge-only policy; replaced Fastify app.inject testing guidance with Supertest/Jest defaults; widened scoped Plan Forge instruction globs to **; and reintroduced 39 configured project-name placeholders across guides. The setup validator still reported 33 passed, 0 failed, 0 warnings.

Workaround Applied

Before committing the runtime update, restored the five project-specific instruction files exactly from their known pre-update content, retained path-limited shipping instructions, and restored configured Rummag memory project arguments while keeping genuine v3.26.7 guidance changes. Exact comparisons verified restored instructions match the committed project versions. Updater should preserve consumer customizations or require an explicit conflict decision instead of overwriting them.

Files

• pforge.ps1
• pforge.sh
• .github/instructions/git-workflow.instructions.md
• .github/instructions/security.instructions.md
• .github/instructions/testing.instructions.md
• .github/instructions/context-fuel.instructions.md
• .github/instructions/self-repair-reporting.instructions.md
• .github/prompts/step6-ship.prompt.md

[srnichols]

Root cause for the testing-guidance part of this issue, found while rehearsing the v3.27.0 release:

• pforge update and self-update treat .github/instructions/testing.instructions.md as a shared, framework-owned file. It is in $sharedInstructions in pforge.ps1 and in the equivalent list in pforge.sh. Every update overwrites it from presets/shared/.github/instructions/testing.instructions.md.
• That shared file is TypeScript guidance ("# TypeScript Testing Patterns"). It has been since 21290d46, when the five consumer instruction files were routed through presets/shared/ (Shipped-template defect (umbrella): 53 Plan-Forge-internal leaks across 6 shared instruction files (fix applied, supersedes #221) #222).
• setup installs the stack's own testing.instructions.md, because the preset copy overrides the shared one. The first update then replaces it. A .NET, Python, Java, Go, Rust, PHP, Swift or Azure IaC project ends up with TypeScript testing patterns. That is the Fastify → Supertest/Jest swap reported above.
• Since v3.27.0 the TypeScript preset's testing guide (Vitest 5, Jest 30, Playwright 1.63) also differs from the shared copy, so a TypeScript project's update now installs the older text as well.

Any design for this issue should either take testing.instructions.md from the project's preset rather than from presets/shared/, or drop it from the shared update list.

[srnichols]

Fixed in v3.28.0.

• pforge update (both shells) passes instruction, prompt, agent, skill, hook and runbook files through pforge-mcp/update-guard.mjs. A file is replaced only when it matches a version Plan Forge shipped (index of every release in pforge-mcp/shipped-guidance-hashes.json), after accounting for the project name, stack and setup date in .forge.json.
• Edited files are kept and listed as KEEP; the new version goes to .forge/update-pending/<path>. --overwrite-customized (update and self-update) replaces them after a backup in .forge/update-backups/<timestamp>/.
• Placeholders are filled in on updated files, including files an older updater left raw.
• Setup and update install a stack preset's own testing and security instructions instead of the shared TypeScript testing file and Plan Forge's internal security rules; projects without a stack preset get new stack-neutral versions.

Note: updating to 3.28.0 still runs the updater you have, so the protection starts with the next update. Commit before updating, or replace pforge.ps1 / pforge.sh with the 3.28.0 copy first. Verified end to end in Git Bash and Windows PowerShell 5.1 (local source and GitHub download).