[tamirdresher]

Summary

• Wrap the Squad .github/copilot-instructions.md template in / markers.
• Add mergeCopilotInstructionsContent,
  emoveCopilotInstructionsBlock, and syncCopilotInstructionsFile in managed-file.ts and wire them into squad upgrade, squad init, and squad copilot.
• Preserve 100% of user-authored .github/copilot-instructions.md content while appending or updating only the Squad-managed block.
• Add unit and regression tests for fresh creation, preserving existing user instructions without markers, and idempotent marker-based upgrades.

Closes #2186

[github-actions]

🟠 Impact Analysis — PR #2221

Risk tier: 🟠 HIGH

📊 Summary

Metric	Count
Files changed	11
Files added	1
Files modified	10
Files deleted	0
Modules touched	5

🎯 Risk Factors

• 11 files changed (6-20 → MEDIUM)
• 5 modules touched (5-8 → HIGH)

📦 Modules Affected

root (2 files)

• .changeset/preserve-copilot-instructions-on-upgrade.md
• templates/copilot-instructions.md

squad-cli (5 files)

• packages/squad-cli/src/cli/commands/copilot.ts
• packages/squad-cli/src/cli/core/init.ts
• packages/squad-cli/src/cli/core/managed-file.ts
• packages/squad-cli/src/cli/core/upgrade.ts
• packages/squad-cli/templates/copilot-instructions.md

squad-sdk (1 file)

• packages/squad-sdk/templates/copilot-instructions.md

templates (1 file)

• .squad-templates/copilot-instructions.md

tests (2 files)

• test/cli/upgrade-portability.test.ts
• test/cli/upgrade.test.ts

---

This report is generated automatically for every PR. See #733 for details.

[github-actions]

🛫 PR Readiness Check

ℹ️ This comment updates on each push. Last checked: commit 0e33392

PR Scope: 📦🔧 Mixed (product + infrastructure)

⚠️ 3 item(s) to address before review

Status	Check	Details
✅	Single commit	1 commit — clean history
✅	Not in draft	Ready for review
✅	Branch up to date	Up to date with dev
❌	Copilot review	No Copilot review yet — it may still be processing
✅	Changeset present	Changeset file found
✅	Scope clean	No .squad/ or docs/proposals/ files
✅	No merge conflicts	No merge conflicts
❌	Copilot threads resolved	1 unresolved Copilot thread(s) — fix and resolve before merging
❌	CI passing	7 check(s) still running

Files Changed (11 files, +232 −10)

File	+/−
.changeset/preserve-copilot-instructions-on-upgrade.md	+5 −0
.squad-templates/copilot-instructions.md	+3 −0
packages/squad-cli/src/cli/commands/copilot.ts	+13 −5
packages/squad-cli/src/cli/core/init.ts	+3 −2
packages/squad-cli/src/cli/core/managed-file.ts	+112 −1
packages/squad-cli/src/cli/core/upgrade.ts	+2 −2
packages/squad-cli/templates/copilot-instructions.md	+3 −0
packages/squad-sdk/templates/copilot-instructions.md	+3 −0
templates/copilot-instructions.md	+3 −0
test/cli/upgrade-portability.test.ts	+5 −0
test/cli/upgrade.test.ts	+80 −0

Total: +232 −10

---

This check runs automatically on every push. Fix any ❌ items and push again.
See CONTRIBUTING.md and PR Requirements for details.

[github-actions]

🏗️ Architectural Review

Authoritative evidence: base-controlled pull_request_target reporter.

⚠️ Architectural review: 1 warning(s).

Severity	Category	Finding	Files
🟡 warning	bootstrap-area	3 file(s) in the bootstrap area (packages/squad-cli/src/cli/core/) were modified. These files must maintain zero external dependencies. Review carefully.	packages/squad-cli/src/cli/core/init.ts, packages/squad-cli/src/cli/core/managed-file.ts, packages/squad-cli/src/cli/core/upgrade.ts

---

Automated architectural review — informational only.

[Copilot]

🟡 Changes recommended

Malformed or ambiguous markers can still delete user content, and the template mirrors and release changeset are incomplete.

5 open findings

• Avoid pairing unmatched start markers with later end markers · New
• Require both legacy sentinels before replacing file content · New
• Edit canonical template instead of generated mirror · New
• Edit canonical template instead of generated mirror · New
• Declare SDK patch release for template changes · New

What changed in this PR

Adds managed markers so Squad updates its Copilot instructions without overwriting user content.

Changes:

• Adds merge, removal, and synchronization helpers.
• Integrates them with upgrade, init, and Copilot commands.
• Adds upgrade and portability regressions.

File	Description
managed-file.ts	Implements managed-block handling.
upgrade.ts	Preserves instructions during upgrades.
init.ts	Merges instructions during initialization.
copilot.ts	Upserts or removes only Squad instructions.
CLI template	Adds managed markers.
SDK template	Adds managed markers.
upgrade.test.ts	Tests creation and preservation.
upgrade-portability.test.ts	Tests CRLF preservation.
Changeset	Documents the CLI fix.

---

_{Review effort: Balanced}