chore: integrate Teams notifications with squad workflow

Copilot · Copilot · commit 1f76c1aec0f6 · 2026-03-12T07:09:19.000-07:00
Merge decisions inbox into team memory and add Teams notification support
for milestone updates (work batches, PRs, issues, decisions).

Changes:
- Merged 6 decision files from inbox/ into .squad/decisions.md
- Added teams-notify.sh script for Microsoft Graph API integration
- Added teams-test.sh verification companion
- Updated Scribe charter with Teams notification protocols
- Updated team.md with Integrations section
- Updated agent histories (Linus, Livingston)
- Added teams-config.json for channel configuration

Teams notifications now enabled via .squad/scripts/teams-notify.sh with
event filtering, HTML escaping, and graceful error handling (never breaks
CI/CD).

Co-authored-by: Copilot &lt;223556219+Copilot@users.noreply.github.com&gt;
diff --git a/.squad/agents/linus/history.md b/.squad/agents/linus/history.md
@@ -93,6 +93,14 @@ All code roles now use `claude-opus-4.6`. Docs/Scribe/diversity use `gemini-3-pr
 - **What:** Added `waza suggest <skill-path>` for LLM-driven eval generation. Command supports `--model`, `--dry-run` (default), `--apply`, `--output-dir`, and `--format yaml|json`. New `internal/suggest` package builds prompt context from SKILL.md + grader types + eval schema summary + example eval, parses structured YAML responses, validates generated `eval_yaml`, and writes `eval.yaml`/task/fixture files when applying.
 - **Key learning:** A robust parser needs to handle both structured wrapper YAML (`eval_yaml` + files) and fenced YAML blocks from models. Validating generated `eval_yaml` against `models.BenchmarkSpec.Validate()` catches malformed model output early before writing files.
 
+### Teams Notification Scripts
+- **Date:** 2026-03-12
+- **Files:** `.squad/scripts/teams-notify.sh`, `.squad/scripts/teams-test.sh`
+- **What:** Created Teams notification script using `az rest` + Microsoft Graph API. Reads config from `.squad/identity/teams-config.json`. Supports 5 event types with per-event enable/disable. HTML-formatted messages with emoji headers. Graceful error handling (never exits non-zero). jq preferred, grep/sed fallback. Companion test script for verification.
+- **Key learning:** `az rest` handles auth token injection automatically when hitting `graph.microsoft.com` — no manual token management needed. Using `jq -n --arg` for JSON body construction is essential to handle HTML content with special chars safely.
+
 ## Learnings
 - Windows local test runs can fail in `cmd/waza/tokens/internal/git` when temporary repos inherit strict CRLF behavior; setting `core.autocrlf=false` and `core.safecrlf=false` inside test repo setup makes these tests cross-platform stable.
 - PR conflict resolution for `copilot/migrate-copilot-client-usage` in `internal/execution/copilot_test.go` should keep the `TestCopilotExecute_InitializePropagatesStartError` variant from main to preserve startup error propagation coverage.
+- Teams Graph API channel messages POST to `/v1.0/teams/{groupId}/channels/{channelId}/messages` with body `{body:{contentType:"html",content:"..."}}`. `az rest` auto-injects bearer tokens for graph.microsoft.com endpoints.
+- Squad notification scripts live in `.squad/scripts/` and config in `.squad/identity/teams-config.json`. The notify script always exits 0 to be safe for caller pipelines.
diff --git a/.squad/agents/livingston/history.md b/.squad/agents/livingston/history.md
@@ -88,3 +88,40 @@ All code roles now use `claude-opus-4.6`. Docs/Scribe/diversity use `gemini-3-pr
 **Site build verified:** All 14 pages built successfully, ci-cd page included
 
 **Branch:** squad/89-ci-integration-guide → PR to microsoft/waza main
+
+## 📌 Skill Documentation: Teams Notifications (2026-03-12)
+
+**Created:** `.squad/skills/teams-notify/SKILL.md`
+
+**What the skill documents:**
+The Teams notification system that the squad uses to communicate milestones to the "Waza Squad" Teams channel. Uses Microsoft Graph API via `az rest` (Azure CLI) — no Power Automate, no webhooks, no app registration.
+
+**Key components documented:**
+1. **Architecture** — Azure CLI (`az rest`) posts to Graph API, Scribe-driven
+2. **Configuration** — teams-config.json with group ID, channel ID, per-event toggles
+3. **Event types** — work_complete, pr_opened, pr_merged, issue_closed, decisions, ralph_status
+4. **Usage** — Manual notifications via `.squad/scripts/teams-notify.sh <event_type> "<message>"`
+5. **Troubleshooting** — Login issues, 403 permissions, channel ID extraction, script not found
+6. **Graceful degradation** — Full functionality without Teams configured, no impact on dev workflow
+7. **Configuration checklist** — Prerequisites and test procedure
+
+**Key design patterns established:**
+- Master `enabled` toggle gates all notifications
+- Per-event toggles allow selective notification (e.g., decisions=true, ralph_status=false)
+- Script pattern: read config → check enabled and event type → format → post → exit silently on disable
+- Teams channel ID extracted from Teams UI (right-click → copy link) or Azure CLI
+- No retry logic — fire-and-forget HTTP POST to Graph API
+
+**File paths:**
+- Skill document: `.squad/skills/teams-notify/SKILL.md`
+- Configuration: `.squad/identity/teams-config.json`
+- Script location (for user reference): `.squad/scripts/teams-notify.sh` (not yet created; documented as expected location)
+- Graph API endpoint: `/me/teamwork/sendActivityNotification` (documented in See Also)
+
+**Clarity improvements over requirements:**
+- Added mermaid-like flow diagram to show architecture
+- Included step-by-step channel ID extraction procedure (Teams UI + CLI)
+- Provided schema table with field descriptions
+- Added troubleshooting decision tree with specific `az` commands to test
+- Clarified graceful degradation (no errors, no noise when disabled)
+- Included configuration checklist with pre-flight items
diff --git a/.squad/agents/scribe/charter.md b/.squad/agents/scribe/charter.md
@@ -47,6 +47,25 @@ Never start work unprompted. Scribe is always spawned after substantial work by
 
 Always run in `mode: "background"` — non-blocking, async logging.
 
+## Teams Notifications
+
+After completing logging and decision merging tasks, check if Teams notifications are enabled:
+
+1. Read `.squad/identity/teams-config.json`
+2. If `enabled` is `true`, call `.squad/scripts/teams-notify.sh` with the appropriate event type and a brief summary
+3. Event type mapping:
+   - After a work batch → `work_complete` with agent names and what they did
+   - After PR creation → `pr_opened` with PR number, title, and branch
+   - After PR merge → `pr_merged` with PR number and title
+   - After issue close → `issue_closed` with issue number and title
+   - After decision merge → `decisions` with the decision summary
+4. If the script fails or Teams is not configured, continue normally — notifications never block logging
+
+The script handles all formatting and auth. Scribe just calls it with the event type and message string:
+```bash
+.squad/scripts/teams-notify.sh work_complete "🔧 Linus refactored auth module. 🧪 Basher added 12 test cases."
+```
+
 ## Voice
 
 Quiet. Observant. The institutional memory of the team. Doesn't have opinions, just facts. Makes sure decisions don't get lost.
diff --git a/.squad/decisions.md b/.squad/decisions.md
@@ -399,3 +399,129 @@ All issues routed to qualified squad members:
 | #89 | CI/CD integration guide (P1) | squad:livingston + squad:saul | Documentation with doc-review gate |
 
 **Why:** Batch review + triage ensures all green PRs merge cleanly and new work is routed to the right specialist without manual coordination. Parallel work begins immediately once triage is complete.
+
+## 2026-03-10: PR Feedback Pass 2 — Design Decision Rationale
+
+**By:** Linus (Backend Developer)
+**Date:** 2026-03-10
+
+**What:** Resolved all 49 unresolved review threads across PRs #79–#96. Key design decisions documented:
+
+1. **Trigger grader empty prompt handling** (PR #90): Empty prompts now fail immediately. Previously score=0 in negative mode would pass (0 < threshold), a false positive.
+
+2. **Snapshot path resolution** (PR #95): `resolvePathWithSymlinks` now recursively walks up the path tree, enabling snapshot writes to non-existent intermediate directories. This was blocking the parent-dir-creation use case.
+
+3. **Coverage threshold** (PR #92): ≥2 grader types for "Full" coverage is intentional — a single grader validates one dimension; multi-angle coverage requires multiple grader types. Documented in code.
+
+4. **Base ref fallback chain** (PR #93): Changed from origin/main → main to origin/main → main → HEAD per chlowell's review. Enables diff command in repos without remotes.
+
+**Why:** Clearing the review feedback backlog to unblock merge queue. All human reviewer feedback (wbreza, chlowell) addressed with code or rationale. Copilot automated comments assessed individually — genuine bugs fixed, design choices documented and resolved.
+
+**Impact:** All 8 authored PRs now have 0 unresolved threads and are ready for merge.
+
+## 2026-03-10: Fork PR Branch Fix Protocol
+
+**By:** Linus (Backend Developer)
+**Date:** 2026-03-10
+
+**What:** When squad feedback sweep commits land on the wrong remote (origin/microsoft instead of fork/spboyer), the fix protocol is:
+
+1. Fetch both remotes
+2. Compare `origin/<branch>` vs `fork/<branch>` — identify unique origin commits by deduplicating on commit message
+3. Create detached worktrees from fork branch tips
+4. Cherry-pick only unique, architecturally-compatible commits (skip commits targeting superseded code)
+5. Push to fork remote
+6. Verify PR head SHA advanced on GitHub
+
+**Key rule for #93 (tokens diff):** When a fork branch was independently reworked (diff→compare consolidation), do NOT cherry-pick old fix commits that target removed code. Only cherry-pick architecture-neutral commits (docs, CHANGELOG).
+
+**Why:** Fork-backed PRs only advance when the fork branch moves. Pushing to origin branches (same name) has no effect on the PR. This protocol avoids introducing conflicts from stale commits while ensuring all review feedback reaches the actual PR.
+
+**Impact:** All future feedback sweeps must verify they're pushing to the correct remote (`fork` for fork-backed PRs, `origin` for origin-backed PRs) before pushing. Check `gh pr view <N> --json headRepository` to confirm.
+
+## 2026-03-10: hasConfiguredTokenLimits: non-nil pointer = authoritative
+
+**By:** Linus (Backend Developer)
+**PR:** #96
+**Date:** 2026-03-10
+
+**What:** `hasConfiguredTokenLimits` now returns `true` for any non-nil `*TokenLimitsConfig` pointer, not just when Defaults or Overrides maps are populated. This means `tokens.limits: {}` in `.waza.yaml` is treated as authoritative and suppresses the deprecated `.token-limits.json` fallback.
+
+**Why:** A non-nil pointer from YAML unmarshaling means the user explicitly declared the section. Requiring populated child maps created a semantic gap where `limits: {}` silently fell back to legacy JSON — surprising behavior during migration.
+
+**Impact:** Users migrating from `.token-limits.json` to `.waza.yaml` can now safely write an empty `tokens.limits:` section to disable the legacy fallback before populating their limits.
+
+## 2026-03-12: Teams Notification Script Design
+
+**By:** Linus (Backend Developer)
+**Date:** 2026-03-12
+
+### Context
+
+Created `.squad/scripts/teams-notify.sh` for sending squad notifications to the Waza Squad Teams channel via Microsoft Graph API.
+
+### Decisions
+
+1. **Always exit 0** — The notification script never returns a non-zero exit code. If az isn't installed, not logged in, config is missing, or the API call fails, it logs a warning to stderr and exits cleanly. This prevents notification failures from breaking CI/CD pipelines or squad automation.
+
+2. **jq with grep/sed fallback** — Uses jq for JSON parsing when available, falls back to grep/sed for environments without jq. The jq path is preferred because it properly handles JSON escaping in the request body.
+
+3. **HTML content escaping** — Message content is escaped (`&`, `<`, `>`, `"`) before embedding in HTML to prevent injection in Teams messages.
+
+4. **Config-driven event filtering** — Each event type can be independently enabled/disabled in `teams-config.json` via the `notify_on` object. The script checks this before making any API call.
+
+5. **TEAM_ROOT resolution** — Script auto-detects the team root by walking up from its own location (`../../` from `.squad/scripts/`). Can be overridden via `TEAM_ROOT` env var.
+
+### Files
+
+- `.squad/scripts/teams-notify.sh` — Main notification script
+- `.squad/scripts/teams-test.sh` — Test/verification companion
+- `.squad/identity/teams-config.json` — Channel config (pre-existing)
+
+
+## 2026-03-12: Microsoft Teams Notifications via Graph API
+
+**By:** Coordinator (in consultation with Linus and Shayne Boyer)  
+**Date:** 2026-03-12T13:45Z  
+**Related:** User directive (2026-03-12)
+
+**What:** Implemented Teams notifications for squad milestone updates via Microsoft Graph API. System sends notifications to "Waza Squad" Teams channel on work batches, PR lifecycle, issue closure, and decision merges.
+
+**Components:**
+- **Script:** `.squad/scripts/teams-notify.sh` — Main notification sender
+- **Test:** `.squad/scripts/teams-test.sh` — Verification tool
+- **Config:** `.squad/identity/teams-config.json` — Channel config (pre-existing)
+- **Skill:** `.squad/skills/teams-notify/SKILL.md` — Usage documentation
+
+**Design Decisions:**
+
+1. **Always exit 0** — Notification failures never block automation. Graceful degradation: if az isn't installed, not logged in, config missing, or API fails, the script logs a warning to stderr and exits cleanly.
+
+2. **jq with grep/sed fallback** — JSON parsing prefers jq (proper HTML/JSON escaping) but falls back to grep/sed for minimal environments without jq installed.
+
+3. **HTML content escaping** — Message content escaped for `&`, `<`, `>`, `"` before embedding in Teams HTML to prevent injection vulnerabilities.
+
+4. **Config-driven event filtering** — Each event type (`work_complete`, `pr_opened`, `pr_merged`, `issue_closed`, `decisions`) independently controllable via `notify_on` object in teams-config.json. Allows disabling noisy events while keeping critical ones.
+
+5. **TEAM_ROOT auto-detection** — Script walks up from its location (`../../` from `.squad/scripts/`) to find repo root. Can be overridden via `TEAM_ROOT` environment variable for CI/CD flexibility.
+
+**Event Types:**
+- `work_complete` — Agent work batch summaries (names + what they did)
+- `pr_opened` — New PR (number, title, branch)
+- `pr_merged` — Merged PR (number, title)
+- `issue_closed` — Closed issue (number, title)
+- `decisions` — Decision merges (summary)
+
+**Integration:**
+- Scribe calls notification system after completing logging tasks
+- All agents can manually trigger notifications for their work
+- Coordinator uses for orchestration milestones
+- Failures never block automation — entirely optional enhancement
+
+**Testing:**
+- `.squad/scripts/teams-test.sh` verified notification delivery to Teams
+- Message successfully appeared in "Waza Squad" channel
+- No blocking errors observed
+
+**Why:**
+User request (Shayne Boyer) to send squad milestone updates to Teams channel. System enables real-time team awareness of work completion, PRs, and decisions without requiring polling or manual updates. Designed to never interfere with CI/CD or squad automation — a pure enhancement to team communication.
diff --git a/.squad/identity/teams-config.json b/.squad/identity/teams-config.json
@@ -0,0 +1,14 @@
+{
+  "enabled": true,
+  "group_id": "450e4e32-11f8-4436-a9b4-4990ae16fe58",
+  "channel_id": "19:288df9bbfec84a1da3aec636c7b829a5@thread.tacv2",
+  "channel_name": "Waza Squad",
+  "notify_on": {
+    "work_complete": true,
+    "pr_opened": true,
+    "pr_merged": true,
+    "issue_closed": true,
+    "decisions": true,
+    "ralph_status": false
+  }
+}
diff --git a/.squad/log/2026-03-12T13-45-teams-integration.md b/.squad/log/2026-03-12T13-45-teams-integration.md
@@ -0,0 +1,33 @@
+# Session Log: Teams Integration Sprint
+**Date:** 2026-03-12T13:45:00Z
+
+## Work Batch
+
+**Participants:** Linus (Backend), Livingston (Documentation), Coordinator
+
+## What Shipped
+
+- **Notification System** — `.squad/scripts/teams-notify.sh` for Teams milestone updates via Microsoft Graph API
+- **Test Suite** — `.squad/scripts/teams-test.sh` verified notification delivery
+- **Skill Documentation** — `.squad/skills/teams-notify/SKILL.md` with comprehensive usage guide
+- **Configuration** — `.squad/identity/teams-config.json` with event filtering controls
+- **Decision Records** — Merged inbox decisions into team memory
+
+## Event Types
+
+- `work_complete` — Agent work batch summaries
+- `pr_opened` / `pr_merged` — Pull request lifecycle
+- `issue_closed` — Issue closure
+- `decisions` — Decision merges
+
+## Key Design
+
+All notifications exit 0 — failures never block automation. JSON parsing falls back gracefully. HTML content properly escaped. Event types independently configurable.
+
+## Verification
+
+Test notification successfully delivered to "Waza Squad" Teams channel.
+
+## Team Notes
+
+System ready for use. Scribe can now call notifications for future work batches. All documentation current.
diff --git a/.squad/orchestration-log/2026-03-12T13-45-linus-teams-notify.md b/.squad/orchestration-log/2026-03-12T13-45-linus-teams-notify.md
@@ -0,0 +1,48 @@
+# Orchestration: Linus — Teams Notification System
+**Date:** 2026-03-12T13:45:00Z  
+**Agent:** Linus (Backend Developer)  
+**Mode:** background  
+**Outcome:** ✅ success
+
+## Work Summary
+
+Created the Teams notification system for squad milestone updates via Microsoft Graph API.
+
+## Artifacts
+
+### Code
+- **`.squad/scripts/teams-notify.sh`** — Main notification script
+  - Sends messages to Teams channel via Microsoft Graph API (`az rest`)
+  - Supports multiple event types: `work_complete`, `pr_opened`, `pr_merged`, `issue_closed`, `decisions`
+  - Event filtering driven by `.squad/identity/teams-config.json`
+  - Always exits 0 — notification failures never block automation
+  - Robust: Falls back from jq to grep/sed for JSON parsing
+  - HTML content escaping for security
+
+- **`.squad/scripts/teams-test.sh`** — Test/verification companion
+  - Standalone test of notification delivery to Teams
+  - Verified notification appeared in Waza Squad channel
+
+## Design Decisions
+
+1. **Always exit 0** — Notification script handles all errors gracefully. If az isn't installed, not logged in, config missing, or API fails, it logs warning and exits cleanly.
+
+2. **jq with grep/sed fallback** — JSON parsing prefers jq (proper escaping) but falls back to grep/sed for minimal environments.
+
+3. **HTML content escaping** — Message content escaped (`&`, `<`, `>`, `"`) before embedding in Teams HTML.
+
+4. **Config-driven event filtering** — Each event type independently controlled via `notify_on` object in teams-config.json.
+
+5. **TEAM_ROOT auto-detection** — Script walks up from location to find repo root. Can be overridden via env var.
+
+## Verification
+
+- Test notification sent via `teams-test.sh`
+- Message successfully delivered to "Waza Squad" Teams channel
+- No blocking errors observed
+
+## Next Steps
+
+- Scribe will merge decisions and call notifications after logging
+- Livingston to document skill
+- Coordinator to verify integration completeness
diff --git a/.squad/orchestration-log/2026-03-12T13-45-livingston-teams-skill.md b/.squad/orchestration-log/2026-03-12T13-45-livingston-teams-skill.md
@@ -0,0 +1,40 @@
+# Orchestration: Livingston — Teams Notification Skill
+**Date:** 2026-03-12T13:45:00Z  
+**Agent:** Livingston (Documentation Specialist)  
+**Mode:** background  
+**Outcome:** ✅ success
+
+## Work Summary
+
+Created comprehensive skill documentation for the Teams notification system.
+
+## Artifacts
+
+### Documentation
+- **`.squad/skills/teams-notify/SKILL.md`** — Full Teams notification skill
+  - Explains purpose and usage of notification system
+  - Documents all event types and when to trigger them
+  - Shows example calls and expected Teams message format
+  - References configuration at `.squad/identity/teams-config.json`
+  - Provides troubleshooting section for common issues
+  - Includes script exit codes and error handling notes
+
+## Key Sections
+
+1. **Overview** — Teams notifications via Graph API for squad milestones
+2. **Event Types** — work_complete, pr_opened, pr_merged, issue_closed, decisions
+3. **Usage** — How and when to call `.squad/scripts/teams-notify.sh`
+4. **Configuration** — teams-config.json format and event filtering
+5. **Examples** — Real example calls and message formatting
+6. **Troubleshooting** — Common issues and solutions
+
+## Integration Points
+
+- Scribe calls this after logging other team work
+- Coordinator invokes during setup or manual milestone recording
+- All agents can trigger notifications for their work
+
+## Next Steps
+
+- Scribe will merge decisions and use this skill for notification
+- Integration complete once Coordinator verifies
diff --git a/.squad/scripts/teams-notify.sh b/.squad/scripts/teams-notify.sh
diff --git a/.squad/scripts/teams-test.sh b/.squad/scripts/teams-test.sh
diff --git a/.squad/skills/teams-notify/SKILL.md b/.squad/skills/teams-notify/SKILL.md
diff --git a/.squad/team.md b/.squad/team.md
