fix: eliminate PR contamination from broad git staging (#777)

.copilot/skills/git-workflow/SKILL.md

@@ -99,7 +99,8 @@ Each agent operates inside its worktree exactly like the single-issue workflow:
 cd ../squad-195
 
 # Work normally — commits, tests, pushes
-git add -A && git commit -m "fix: stamp bug (#195)"
+# ⚠️ NEVER use `git add .`, `git add -A`, or other broad staging commands
+git add -- {specific files you modified} && git commit -m "fix: stamp bug (#195)"
 git push -u origin squad/195-fix-stamp-bug
 
 # Create PR targeting dev

.copilot/skills/windows-compatibility/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: "windows-compatibility"
+description: "Cross-platform path handling and command patterns"
+domain: "platform"
+confidence: "high"
+source: "earned (multiple Windows-specific bugs: colons in filenames, git -C failures, path separators)"
+---
+
+## Context
+
+Squad runs on Windows, macOS, and Linux. Several bugs have been traced to platform-specific assumptions: ISO timestamps with colons (illegal on Windows), `git -C` with Windows paths (unreliable), forward-slash paths in Node.js on Windows.
+
+## Patterns
+
+### Filenames & Timestamps
+- **Never use colons in filenames:** ISO 8601 format `2026-03-15T05:30:00Z` is illegal on Windows
+- **Use `safeTimestamp()` utility:** Replaces colons with hyphens → `2026-03-15T05-30-00Z`
+- **Centralize formatting:** Don't inline `.toISOString().replace(/:/g, '-')` — use the utility
+
+### Git Commands
+- **Never use `git -C {path}`:** Unreliable with Windows paths (backslashes, spaces, drive letters)
+- **Always `cd` first:** Change directory, then run git commands
+- **Check for changes before commit:** `git diff --cached --quiet` (exit 0 = no changes)
+
+### Commit Messages
+- **Never embed newlines in `-m` flag:** Backtick-n (`\n`) fails silently in PowerShell
+- **Use temp file + `-F` flag:** Write message to file, commit with `git commit -F $msgFile`
+
+### Paths
+- **Never assume CWD is repo root:** Always use `TEAM ROOT` from spawn prompt or run `git rev-parse --show-toplevel`
+- **Use path.join() or path.resolve():** Don't manually concatenate with `/` or `\`
+
+## Examples
+
+✓ **Correct:**
+```powershell
+// Timestamp utility
+const safeTimestamp = () => new Date().toISOString().replace(/:/g, '-').split('.')[0] + 'Z';
+
+// Git workflow (PowerShell)
+cd $teamRoot
+# ⚠️ NEVER use `git add .squad/` or broad globs — only stage files you intentionally changed
+# Stage only files you actually modified — use git status to build explicit list
+$filesToStage = git status --porcelain | Where-Object { $_.Length -gt 3 } | ForEach-Object { $_.Substring(3) -replace '^.* -> ','' } | Where-Object {
+  $_ -eq '.squad/decisions.md' -or
+  $_ -eq '.squad/decisions-archive.md' -or
+  $_ -like '.squad/agents/*/history.md' -or
+  $_ -like '.squad/agents/*/history-archive.md' -or
+  $_ -like '.squad/log/*' -or
+  $_ -like '.squad/orchestration-log/*'
+}
+if ($filesToStage) { $filesToStage | Where-Object { $_ } | ForEach-Object { git add -- $_ } }
+git diff --cached --quiet
+if ($LASTEXITCODE -ne 0) {
+  $msg = @"
+docs(ai-team): session log
+
+Changes:
+- Added decisions
+"@
+  $msgFile = [System.IO.Path]::GetTempFileName()
+  Set-Content -Path $msgFile -Value $msg -Encoding utf8
+  git commit -F $msgFile
+  Remove-Item $msgFile
+}
+```
+
+✗ **Incorrect:**
+```javascript
+// Colon in filename
+const logPath = `.squad/log/${new Date().toISOString()}.md`; // ILLEGAL on Windows
+
+// git -C with Windows path
+exec('git -C C:\\src\\squad add .squad/'); // UNRELIABLE
+
+// Inline newlines in commit message
+exec('git commit -m "First line\nSecond line"'); // FAILS silently in PowerShell
+```
+
+## Anti-Patterns
+
+- Testing only on one platform (bugs ship to other platforms)
+- Assuming Unix-style paths work everywhere
+- Using `git -C` because it "looks cleaner" (it doesn't work)
+- Skipping `git diff --cached --quiet` check (creates empty commits)

.github/agents/squad.agent.md

@@ -882,7 +882,7 @@ prompt: |
   4. SESSION LOG: Write .squad/log/{timestamp}-{topic}.md. Brief. Use ISO 8601 UTC timestamp.
   5. CROSS-AGENT: Append team updates to affected agents' history.md.
   6. HISTORY SUMMARIZATION [HARD GATE]: If any history.md >= 15360 bytes (15KB), summarize now.
-  7. GIT COMMIT: git add .squad/ && commit (write msg to temp file, use -F). Skip if nothing staged.
+  7. GIT COMMIT: Stage only the exact `.squad/` files Scribe wrote in this session. Use `git status --porcelain` filtered to allowed paths (decisions.md, decisions-archive.md, agents/{name}/history.md, agents/{name}/history-archive.md, log/*, orchestration-log/*). Stage each file individually with `git add -- <path>`. Handle renames by extracting destination path (`-replace '^.* -> ',''`). Commit with -F (write msg to temp file). Skip if nothing staged. ⚠️ NEVER use `git add .squad/` or broad globs.
   8. HEALTH REPORT: Log decisions.md before/after size, inbox count processed, history files summarized.
 
   Never speak to user. ⚠️ End with plain text summary after all tool calls.

.squad-templates/issue-lifecycle.md

@@ -231,7 +231,8 @@ Working as {member} ({role})
 **Update workflow:**
 ```bash
 # Make changes
-git add .
+# ⚠️ NEVER use `git add .` or `git add -A` — only stage files you intentionally changed
+git add -- {specific files you modified}
 git commit -m "fix: address review feedback"
 git push
 ```

.squad-templates/scribe-charter.md

@@ -61,7 +61,26 @@ After every substantial work session:
    Do NOT embed newlines in `git commit -m` (backtick-n fails silently in PowerShell).
    Instead:
    - `cd` into the team root first.
-   - Stage all `.squad/` files: `git add .squad/`
+   - Stage only files Scribe actually modified in this session.
+     Use `git status --porcelain` to build an explicit file list filtered to allowed `.squad/` paths:
+     ```powershell
+     $allowed = @(
+       '.squad/decisions.md',
+       '.squad/decisions-archive.md'
+     )
+     $allowedPatterns = @(
+       '.squad/agents/*/history.md',
+       '.squad/agents/*/history-archive.md',
+       '.squad/log/*',
+       '.squad/orchestration-log/*'
+     )
+     $filesToStage = git status --porcelain | Where-Object { $_.Length -gt 3 } | ForEach-Object { $_.Substring(3) -replace '^.* -> ','' } | Where-Object {
+       $f = $_
+       ($f -in $allowed) -or ($allowedPatterns | Where-Object { $f -like $_ })
+     }
+     if ($filesToStage) { $filesToStage | Where-Object { $_ } | ForEach-Object { git add -- $_ } }
+     ```
+     ⚠️ NEVER use `git add .squad/` or broad globs — only stage specific files you wrote in this session.
    - Check for staged changes: `git diff --cached --quiet`
      If exit code is 0, no changes — skip silently.
    - Write the commit message to a temp file, then commit with `-F`:

.squad-templates/squad.agent.md

@@ -882,7 +882,7 @@ prompt: |
   4. SESSION LOG: Write .squad/log/{timestamp}-{topic}.md. Brief. Use ISO 8601 UTC timestamp.
   5. CROSS-AGENT: Append team updates to affected agents' history.md.
   6. HISTORY SUMMARIZATION [HARD GATE]: If any history.md >= 15360 bytes (15KB), summarize now.
-  7. GIT COMMIT: git add .squad/ && commit (write msg to temp file, use -F). Skip if nothing staged.
+  7. GIT COMMIT: Stage only the exact `.squad/` files Scribe wrote in this session. Use `git status --porcelain` filtered to allowed paths (decisions.md, decisions-archive.md, agents/{name}/history.md, agents/{name}/history-archive.md, log/*, orchestration-log/*). Stage each file individually with `git add -- <path>`. Handle renames by extracting destination path (`-replace '^.* -> ',''`). Commit with -F (write msg to temp file). Skip if nothing staged. ⚠️ NEVER use `git add .squad/` or broad globs.
   8. HEALTH REPORT: Log decisions.md before/after size, inbox count processed, history files summarized.
 
   Never speak to user. ⚠️ End with plain text summary after all tool calls.

packages/squad-cli/templates/ceremonies.md

@@ -39,3 +39,31 @@
 2. Root cause analysis
 3. What should change?
 4. Action items for next iteration
+
+
+---
+
+## Retrospective with Enforcement
+
+| Field | Value |
+|-------|-------|
+| **Trigger** | auto |
+| **When** | weekly |
+| **Condition** | No *retrospective* log in .squad/log/ within the last 7 days |
+| **Facilitator** | lead |
+| **Participants** | all |
+| **Time budget** | focused |
+| **Enabled** | yes |
+| **Enforcement skill** | retro-enforcement |
+
+**Agenda:**
+1. What shipped this week? (closed issues, merged PRs)
+2. What did not ship? (open issues, blockers)
+3. Root cause on any failures
+4. Action items -- each MUST become a GitHub Issue labeled retro-action
+
+**Coordinator integration:**
+At round start, call Test-RetroOverdue (see skill retro-enforcement). If overdue, run this ceremony before the work queue.
+
+**Why GitHub Issues, not markdown:**
+Production data: 0% completion across 6 retros using markdown checklists, 100% after switching to GitHub Issues.

packages/squad-cli/templates/issue-lifecycle.md

@@ -231,7 +231,8 @@ Working as {member} ({role})
 **Update workflow:**
 ```bash
 # Make changes
-git add .
+# ⚠️ NEVER use `git add .` or `git add -A` — only stage files you intentionally changed
+git add -- {specific files you modified}
 git commit -m "fix: address review feedback"
 git push
 ```

packages/squad-cli/templates/scribe-charter.md

@@ -61,7 +61,26 @@ After every substantial work session:
    Do NOT embed newlines in `git commit -m` (backtick-n fails silently in PowerShell).
    Instead:
    - `cd` into the team root first.
-   - Stage all `.squad/` files: `git add .squad/`
+   - Stage only files Scribe actually modified in this session.
+     Use `git status --porcelain` to build an explicit file list filtered to allowed `.squad/` paths:
+     ```powershell
+     $allowed = @(
+       '.squad/decisions.md',
+       '.squad/decisions-archive.md'
+     )
+     $allowedPatterns = @(
+       '.squad/agents/*/history.md',
+       '.squad/agents/*/history-archive.md',
+       '.squad/log/*',
+       '.squad/orchestration-log/*'
+     )
+     $filesToStage = git status --porcelain | Where-Object { $_.Length -gt 3 } | ForEach-Object { $_.Substring(3) -replace '^.* -> ','' } | Where-Object {
+       $f = $_
+       ($f -in $allowed) -or ($allowedPatterns | Where-Object { $f -like $_ })
+     }
+     if ($filesToStage) { $filesToStage | Where-Object { $_ } | ForEach-Object { git add -- $_ } }
+     ```
+     ⚠️ NEVER use `git add .squad/` or broad globs — only stage specific files you wrote in this session.
    - Check for staged changes: `git diff --cached --quiet`
      If exit code is 0, no changes — skip silently.
    - Write the commit message to a temp file, then commit with `-F`:

packages/squad-cli/templates/squad.agent.md.template

@@ -882,7 +882,7 @@ prompt: |
   4. SESSION LOG: Write .squad/log/{timestamp}-{topic}.md. Brief. Use ISO 8601 UTC timestamp.
   5. CROSS-AGENT: Append team updates to affected agents' history.md.
   6. HISTORY SUMMARIZATION [HARD GATE]: If any history.md >= 15360 bytes (15KB), summarize now.
-  7. GIT COMMIT: git add .squad/ && commit (write msg to temp file, use -F). Skip if nothing staged.
+  7. GIT COMMIT: Stage only the exact `.squad/` files Scribe wrote in this session. Use `git status --porcelain` filtered to allowed paths (decisions.md, decisions-archive.md, agents/{name}/history.md, agents/{name}/history-archive.md, log/*, orchestration-log/*). Stage each file individually with `git add -- <path>`. Handle renames by extracting destination path (`-replace '^.* -> ',''`). Commit with -F (write msg to temp file). Skip if nothing staged. ⚠️ NEVER use `git add .squad/` or broad globs.
   8. HEALTH REPORT: Log decisions.md before/after size, inbox count processed, history files summarized.
 
   Never speak to user. ⚠️ End with plain text summary after all tool calls.

packages/squad-sdk/templates/ceremonies.md

@@ -39,3 +39,31 @@
 2. Root cause analysis
 3. What should change?
 4. Action items for next iteration
+
+
+---
+
+## Retrospective with Enforcement
+
+| Field | Value |
+|-------|-------|
+| **Trigger** | auto |
+| **When** | weekly |
+| **Condition** | No *retrospective* log in .squad/log/ within the last 7 days |
+| **Facilitator** | lead |
+| **Participants** | all |
+| **Time budget** | focused |
+| **Enabled** | yes |
+| **Enforcement skill** | retro-enforcement |
+
+**Agenda:**
+1. What shipped this week? (closed issues, merged PRs)
+2. What did not ship? (open issues, blockers)
+3. Root cause on any failures
+4. Action items -- each MUST become a GitHub Issue labeled retro-action
+
+**Coordinator integration:**
+At round start, call Test-RetroOverdue (see skill retro-enforcement). If overdue, run this ceremony before the work queue.
+
+**Why GitHub Issues, not markdown:**
+Production data: 0% completion across 6 retros using markdown checklists, 100% after switching to GitHub Issues.

packages/squad-sdk/templates/issue-lifecycle.md

@@ -231,7 +231,8 @@ Working as {member} ({role})
 **Update workflow:**
 ```bash
 # Make changes
-git add .
+# ⚠️ NEVER use `git add .` or `git add -A` — only stage files you intentionally changed
+git add -- {specific files you modified}
 git commit -m "fix: address review feedback"
 git push
 ```

packages/squad-sdk/templates/scribe-charter.md

@@ -61,7 +61,26 @@ After every substantial work session:
    Do NOT embed newlines in `git commit -m` (backtick-n fails silently in PowerShell).
    Instead:
    - `cd` into the team root first.
-   - Stage all `.squad/` files: `git add .squad/`
+   - Stage only files Scribe actually modified in this session.
+     Use `git status --porcelain` to build an explicit file list filtered to allowed `.squad/` paths:
+     ```powershell
+     $allowed = @(
+       '.squad/decisions.md',
+       '.squad/decisions-archive.md'
+     )
+     $allowedPatterns = @(
+       '.squad/agents/*/history.md',
+       '.squad/agents/*/history-archive.md',
+       '.squad/log/*',
+       '.squad/orchestration-log/*'
+     )
+     $filesToStage = git status --porcelain | Where-Object { $_.Length -gt 3 } | ForEach-Object { $_.Substring(3) -replace '^.* -> ','' } | Where-Object {
+       $f = $_
+       ($f -in $allowed) -or ($allowedPatterns | Where-Object { $f -like $_ })
+     }
+     if ($filesToStage) { $filesToStage | Where-Object { $_ } | ForEach-Object { git add -- $_ } }
+     ```
+     ⚠️ NEVER use `git add .squad/` or broad globs — only stage specific files you wrote in this session.
    - Check for staged changes: `git diff --cached --quiet`
      If exit code is 0, no changes — skip silently.
    - Write the commit message to a temp file, then commit with `-F`:

packages/squad-sdk/templates/squad.agent.md.template

@@ -882,7 +882,7 @@ prompt: |
   4. SESSION LOG: Write .squad/log/{timestamp}-{topic}.md. Brief. Use ISO 8601 UTC timestamp.
   5. CROSS-AGENT: Append team updates to affected agents' history.md.
   6. HISTORY SUMMARIZATION [HARD GATE]: If any history.md >= 15360 bytes (15KB), summarize now.
-  7. GIT COMMIT: git add .squad/ && commit (write msg to temp file, use -F). Skip if nothing staged.
+  7. GIT COMMIT: Stage only the exact `.squad/` files Scribe wrote in this session. Use `git status --porcelain` filtered to allowed paths (decisions.md, decisions-archive.md, agents/{name}/history.md, agents/{name}/history-archive.md, log/*, orchestration-log/*). Stage each file individually with `git add -- <path>`. Handle renames by extracting destination path (`-replace '^.* -> ',''`). Commit with -F (write msg to temp file). Skip if nothing staged. ⚠️ NEVER use `git add .squad/` or broad globs.
   8. HEALTH REPORT: Log decisions.md before/after size, inbox count processed, history files summarized.
 
   Never speak to user. ⚠️ End with plain text summary after all tool calls.

scripts/sync-templates.mjs

@@ -20,6 +20,21 @@ import { fileURLToPath } from 'node:url';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const ROOT = join(__dirname, '..');
 
+// ---------------------------------------------------------------------------
+// Guard: require explicit invocation to prevent accidental auto-triggering
+// during agent work (e.g., file watchers, git hooks).
+// Pass --sync flag or set SQUAD_SYNC_TEMPLATES=1 env var.
+// ---------------------------------------------------------------------------
+const explicitFlag = process.argv.includes('--sync');
+const envFlag = process.env.SQUAD_SYNC_TEMPLATES === '1';
+const directInvocation = process.argv.length <= 2;
+if (!directInvocation && !explicitFlag && !envFlag) {
+  console.log('⛔ sync-templates requires explicit invocation.');
+  console.log('   Use: node scripts/sync-templates.mjs --sync');
+  console.log('   Or:  SQUAD_SYNC_TEMPLATES=1 node scripts/sync-templates.mjs');
+  process.exit(0);
+}
+
 const SOURCE = join(ROOT, '.squad-templates');
 
 const MIRROR_TARGETS = [

templates/ceremonies.md

@@ -39,3 +39,31 @@
 2. Root cause analysis
 3. What should change?
 4. Action items for next iteration
+
+
+---
+
+## Retrospective with Enforcement
+
+| Field | Value |
+|-------|-------|
+| **Trigger** | auto |
+| **When** | weekly |
+| **Condition** | No *retrospective* log in .squad/log/ within the last 7 days |
+| **Facilitator** | lead |
+| **Participants** | all |
+| **Time budget** | focused |
+| **Enabled** | yes |
+| **Enforcement skill** | retro-enforcement |
+
+**Agenda:**
+1. What shipped this week? (closed issues, merged PRs)
+2. What did not ship? (open issues, blockers)
+3. Root cause on any failures
+4. Action items -- each MUST become a GitHub Issue labeled retro-action
+
+**Coordinator integration:**
+At round start, call Test-RetroOverdue (see skill retro-enforcement). If overdue, run this ceremony before the work queue.
+
+**Why GitHub Issues, not markdown:**
+Production data: 0% completion across 6 retros using markdown checklists, 100% after switching to GitHub Issues.

templates/issue-lifecycle.md

@@ -231,7 +231,8 @@ Working as {member} ({role})
 **Update workflow:**
 ```bash
 # Make changes
-git add .
+# ⚠️ NEVER use `git add .` or `git add -A` — only stage files you intentionally changed
+git add -- {specific files you modified}
 git commit -m "fix: address review feedback"
 git push
 ```