From 3384eafdedc92fa3dfa1b969d443fd190105f951 Mon Sep 17 00:00:00 2001 From: Brady Gaster Date: Fri, 24 Jul 2026 09:42:05 -0700 Subject: [PATCH 1/2] Scribe: Merge decisions inbox and log orchestration session - Merged 5 pending decisions from .squad/decisions/inbox to .squad/decisions.md: - 2026-03-26: CI deletion guard and source tree canary (Booster) - 2026-03-26: Copilot git safety rules (RETRO) - 2026-03-29: Versioning Policy (Flight) - 2026-04-25: Release Process Skill Update (Booster) - 2026-06-24: Restore always-on coordinator inline-dispatch gate (Procedures) - Added orchestration logs for Flight, FIDO, RETRO, Surgeon agents (Session: 2026-07-24T09:20:10.011Z) - Added session log: locked PR merge strategy for 17 open PRs - Deleted merged inbox files (.squad/decisions/inbox/*) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .squad/decisions.md | 82 ++++++++++++++++++- .../2026-07-24T09-20-10-pr-merge-strategy.md | 50 +++++++++++ .../2026-07-24T09-20-10.011-00-00-FIDO.md | 23 ++++++ .../2026-07-24T09-20-10.011-00-00-Flight.md | 27 ++++++ .../2026-07-24T09-20-10.011-00-00-RETRO.md | 25 ++++++ .../2026-07-24T09-20-10.011-00-00-Surgeon.md | 25 ++++++ 6 files changed, 228 insertions(+), 4 deletions(-) create mode 100644 .squad/log/2026-07-24T09-20-10-pr-merge-strategy.md create mode 100644 .squad/orchestration-log/2026-07-24T09-20-10.011-00-00-FIDO.md create mode 100644 .squad/orchestration-log/2026-07-24T09-20-10.011-00-00-Flight.md create mode 100644 .squad/orchestration-log/2026-07-24T09-20-10.011-00-00-RETRO.md create mode 100644 .squad/orchestration-log/2026-07-24T09-20-10.011-00-00-Surgeon.md diff --git a/.squad/decisions.md b/.squad/decisions.md index b438dd5e4..6107836d0 100644 --- a/.squad/decisions.md +++ b/.squad/decisions.md @@ -235,8 +235,82 @@ Triaged 14 untriaged issues (3 docs, 6 community features, 3 bugs, 2 questions). - **Joniba contributions:** Consistently high-quality, matches team standards (wiring guide is excellent). - **Diberry contributions:** MSFT-level quality, merge-ready on delivery. -## Deferred - -- #357, #336, #335, #334, #333, #332, #316 (A2A) — stays shelved per existing decision -- #581 (ADO PRD) — P2, blocked until #341 (SDK-first parity) ships +## Deferred + +- #357, #336, #335, #334, #333, #332, #316 (A2A) — stays shelved per existing decision +- #581 (ADO PRD) — P2, blocked until #341 (SDK-first parity) ships + +--- + +### 2026-03-26: CI deletion guard and source tree canary +**By:** Booster (CI/CD) +**What:** Added two safety checks to squad-ci.yml: (1) source tree canary verifying critical files exist, (2) large deletion guard failing PRs that delete >50 files without 'large-deletion-approved' label. Branch protection on dev requested (may need manual setup). +**Why:** Incident #631 — @copilot deleted 361 files on dev with no CI gate catching it. + +### 2026-03-26: Copilot git safety rules +**By:** RETRO (Security) +**What:** Added mandatory Git Safety section to copilot-instructions.md: prohibits `git add .`, requires feature branches and PRs, adds pre-push checklist, defines red-flag stop conditions. +**Why:** Incident #631 — @copilot used destructive staging on an incomplete working tree, deleting 361 files. + +### 2026-03-29: Versioning Policy — No Prerelease Versions on dev/main +**By:** Flight (Lead) +**Confidence:** Medium (confirmed by PR #640 incident, PR #116 prerelease leak, CI gate implementation) + +**Decision:** +1. All packages use strict semver (`MAJOR.MINOR.PATCH`). No prerelease suffixes on `dev` or `main`. +2. Prerelease versions are ephemeral. `bump-build.mjs` creates `-build.N` for local testing only — never committed. +3. SDK and CLI versions must stay in sync. Divergence silently breaks npm workspace resolution. +4. Surgeon owns version bumps. Other agents must not modify `version` fields in `package.json` unless fixing a prerelease leak. +5. CI enforcement via `prerelease-version-guard` blocks PRs with prerelease versions. `skip-version-check` label is Surgeon-only. + +**Why:** The repo had no documented versioning policy. PR #640 prerelease version `0.9.1-build.4` silently broke workspace resolution. The semver range `>=0.9.0` does not match prerelease versions, causing npm to install a stale registry package. PR #116 Surgeon set versions to `0.9.1-build.1` instead of `0.9.1` on a release branch due to lack of guidance. + +**Impact:** All agents must follow the versioning policy when touching `package.json`. Surgeon charter should reference `.squad/skills/versioning-policy/SKILL.md` for release procedures. CI pipeline enforces the policy via automated gate. + +### 2026-04-25: Release Process Skill Update — v0.9.4 Learnings +**By:** Booster (CI/CD Engineer) +**Status:** Implemented +**Requested by:** Brady + +**Summary:** Updated both release-process skill files with critical learnings from the v0.9.4 release session. The v0.9.4 release was delayed by three distinct issues, each fixed by a separate PR. + +**Files Updated:** +1. `.squad/skills/release-process/SKILL.md` (team-level skill) +2. `.copilot/skills/release-process/SKILL.md` (copilot-level skill) +3. `.squad/agents/booster/history.md` (learnings log) + +**Known Gotchas (Root Cause, Fix PR, Skill Section):** +- Root package.json version drift: squad-release.yml reads from root, not sub-packages (#1043) +- CHANGELOG missing `## [$VERSION]`: Workflow validates version entry exists (#1042) +- Lockfile integrity check rejects workspace packages: Check didn't filter for registry-only packages (#1044) +- GITHUB_TOKEN can't trigger downstream workflows: GitHub security feature prevents event propagation (design decision) +- Prebuild bump breaks workspace linking: bump-build.mjs mutates versions breaking exact match + +**Rationale:** These are high-impact, recurring failure modes. Documenting them in the skill files ensures every agent (human or AI) working on releases has the knowledge to avoid repeating v0.9.4 delays. The GITHUB_TOKEN limitation in particular is non-obvious and would catch any future release. + +### 2026-06-24: Restore always-on coordinator inline-dispatch gate (v0.10.0 regression) +**By:** Procedures (Prompt Engineer) +**Requested by:** Tamir Dresher +**Branch:** squad/fix-coordinator-inline-dispatch-gate (worktree) +**Status:** Proposed — applied in working tree, awaiting Lead (Flight) review; NOT committed. + +**Context:** Matthew Wan reported the main Squad coordinator "does a lot of work on its own instead of using his roster of agents." Worked in v0.9.4, broke in v0.10.0. Commit `afe78188` (#1035, "context overflow sentinel + coordinator size reduction") cut the coordinator template and moved the concrete inline-dispatch gate out of the always-on prompt into lazy-loaded reference files. The leftover inline guidance was too soft. + +**Decision:** Re-establish a strong, always-on dispatch gate without breaking legitimate Direct/Lightweight response modes. Three minimal edits (~14 lines) to the canonical template `.squad-templates/squad.agent.md`: +1. Inline-dispatch gate: inline permitted ONLY in Direct Mode, or when NEITHER `task` NOR `runSubagent` exists; otherwise MUST dispatch. +2. STOP gate: about to emit a domain artifact with no spawn call this turn → STOP and dispatch (exceptions: Direct Mode / no spawn tool). +3. VS Code `runSubagent` micro-playbook re-inlined (~5 lines) so how-to-dispatch is always-on. + +**Synced Copies (canonical first):** +1. `.squad-templates/squad.agent.md` (canonical) +2. `templates/squad.agent.md.template` +3. `.github/agents/squad.agent.md` +4. `packages/squad-cli/templates/squad.agent.md.template` +5. `packages/squad-sdk/templates/squad.agent.md.template` + +**Validation:** Regression test `test/coordinator-inline-dispatch-gate.test.ts` is RED before (8/8 fail), GREEN after (8/8 pass). Full `npm run test` passes deterministic checks. `npm run lint` clean. + +**Changeset:** Required. Added `.changeset/fix-coordinator-inline-dispatch-gate.md` (patch, squad-cli + squad-sdk). + +**Rollout:** Existing installs require `squad upgrade` to pick up the regenerated coordinator agent. diff --git a/.squad/log/2026-07-24T09-20-10-pr-merge-strategy.md b/.squad/log/2026-07-24T09-20-10-pr-merge-strategy.md new file mode 100644 index 000000000..7391af845 --- /dev/null +++ b/.squad/log/2026-07-24T09-20-10-pr-merge-strategy.md @@ -0,0 +1,50 @@ +# Session Log: Locked PR Strategy + +**Date:** 2026-07-24 +**Session Time:** 2026-07-24T09:20:10.011Z +**Requested by:** Brady Gaster +**Agents:** Flight (mission lead), FIDO (QA/CI), RETRO (security), Surgeon (sequencing), Coordinator (orchestration) + +## Summary + +Four-agent stack completed end-to-end audit of 17 open PRs. Disposition locked and prioritized by merge feasibility, security posture, and conflict resolution. + +## PR Disposition (Locked) + +### Merge Now (5 PRs) +- #1511, #1474, #1504, #1510, #1516 + +No conflicts, all tests pass, security clean. Safe for immediate merge in parallel. + +### Close as TS7 (3 PRs) +- #1503, #1506, #1472 + +Duplicates or superseded by other work. No merge impact. + +### Fix Then Merge Chain (2 PRs, Sequential) +- **#1517 → #1525** (ordered pair) + +#1517 must merge first. #1525 depends on #1517's changes. + +### Owner Update Required (3 PRs) +- #1445, #1485, #1414 + +Need author re-baseline or response before merge. Blocked pending communication. + +### Mitigate (3 PRs) +- #1426, #1391, #1392 + +Security findings require custom merge strategy or post-merge mitigation. Not mergeable as-is. + +### Park (1 PR) +- #1529 + +Blocked by external dependency or strategic hold. Deferred. + +## Total Accounting + +17 PRs across 6 disposition buckets. All PRs classified and sequenced. + +## Coordination + +Coordinator posted concise HTML plan to Brady/Tamir Teams chat (message id 1784911185870). diff --git a/.squad/orchestration-log/2026-07-24T09-20-10.011-00-00-FIDO.md b/.squad/orchestration-log/2026-07-24T09-20-10.011-00-00-FIDO.md new file mode 100644 index 000000000..586f7cb1f --- /dev/null +++ b/.squad/orchestration-log/2026-07-24T09-20-10.011-00-00-FIDO.md @@ -0,0 +1,23 @@ +# FIDO Orchestration Log + +**Session:** 2026-07-24T09:20:10.011Z +**Agent:** FIDO (Quality & CI Owner) +**Status:** Completed + +## Task + +Quality and CI/test audit of all 17 open PRs. Identify blockers, test failures, lint issues, and merge readiness. + +## Outcome + +✅ Completed + +Audit findings integrated into Flight's locked disposition plan. Key assessments: +- Test coverage matrix for all PRs +- CI/lint pass/fail status +- Merge dependency analysis +- Release readiness checks + +## Coordination + +Results fed to Flight for sequencing. Findings inform Surgeon's conflict graph. diff --git a/.squad/orchestration-log/2026-07-24T09-20-10.011-00-00-Flight.md b/.squad/orchestration-log/2026-07-24T09-20-10.011-00-00-Flight.md new file mode 100644 index 000000000..bd30cf61e --- /dev/null +++ b/.squad/orchestration-log/2026-07-24T09-20-10.011-00-00-Flight.md @@ -0,0 +1,27 @@ +# Flight Orchestration Log + +**Session:** 2026-07-24T09:20:10.011Z +**Agent:** Flight (Mission Lead) +**Status:** Completed + +## Task + +Initial triage and disposition stack of 17 open PRs. Deep sequential review with locked disposition plan. + +## Outcome + +✅ Completed + +Disposition locked and prioritized: +- **Merge now:** #1511, #1474, #1504, #1510, #1516 (5 PRs) +- **Close as TS7:** #1503, #1506, #1472 (3 PRs) +- **Fix then merge:** #1517 → #1525 chain (2 PRs, sequential) +- **Owner update required:** #1445, #1485, #1414 (3 PRs) +- **Mitigate:** #1426, #1391, #1392 (3 PRs) +- **Park:** #1529 (1 PR) + +Total: 17 PRs accounted for. + +## Coordination + +Final strategy posted to Brady/Tamir Teams chat (message id 1784911185870) by Coordinator. diff --git a/.squad/orchestration-log/2026-07-24T09-20-10.011-00-00-RETRO.md b/.squad/orchestration-log/2026-07-24T09-20-10.011-00-00-RETRO.md new file mode 100644 index 000000000..38396d3ce --- /dev/null +++ b/.squad/orchestration-log/2026-07-24T09-20-10.011-00-00-RETRO.md @@ -0,0 +1,25 @@ +# RETRO Orchestration Log + +**Session:** 2026-07-24T09:20:10.011Z +**Agent:** RETRO (Security & Trust Boundary Auditor) +**Status:** Completed + +## Task + +Security and trust-boundary audit of all 17 open PRs. Identify vault exposure, secret leakage, permission escalation, and boundary violations. + +## Outcome + +✅ Completed + +Security audit findings integrated into disposition plan. Key assessments: +- Credential/secret exposure scan +- Permission boundary analysis +- Hook-based enforcement verification +- Trust-boundary integrity checks + +Results categorized by severity (blocking, mitigate, parked) and inform final merge strategy. + +## Coordination + +Findings incorporated into Coordinator's locked strategy. Mitigate (#1426, #1391, #1392) and park (#1529) decisions reflect security posture. diff --git a/.squad/orchestration-log/2026-07-24T09-20-10.011-00-00-Surgeon.md b/.squad/orchestration-log/2026-07-24T09-20-10.011-00-00-Surgeon.md new file mode 100644 index 000000000..2f109121c --- /dev/null +++ b/.squad/orchestration-log/2026-07-24T09-20-10.011-00-00-Surgeon.md @@ -0,0 +1,25 @@ +# Surgeon Orchestration Log + +**Session:** 2026-07-24T09:20:10.011Z +**Agent:** Surgeon (Merge Sequencer & Conflict Resolution) +**Status:** Completed + +## Task + +Conflict graph analysis and merge sequencing for all 17 open PRs. Identify file conflicts, dependency chains, and safe merge order. + +## Outcome + +✅ Completed + +Sequencing locked: +1. **No-conflict set (merge parallel):** #1511, #1474, #1504, #1510, #1516 +2. **TS7 closures (no merge impact):** #1503, #1506, #1472 +3. **Sequential pair (ordered):** #1517 → #1525 (direct dependency) +4. **Owner updates (re-baselined):** #1445, #1485, #1414 +5. **Mitigated (custom merge strategy):** #1426, #1391, #1392 +6. **Parked (blocked):** #1529 + +## Coordination + +Sequencing validated against Flight's disposition. No merge conflicts or logical dependencies block the locked strategy. From d1bd0e652542a5f0094e845f75be69b1e9640940 Mon Sep 17 00:00:00 2001 From: Brady Gaster Date: Sun, 2 Aug 2026 21:05:43 -0700 Subject: [PATCH 2/2] docs: wire nav-wave-1564 pages into navigation and fix test fixtures Add eight merged docs pages to navigation.ts in their canonical sections: - Guides: Agent Framework Integration (guide/agent-framework-integration) - Security (new section): Security Hardening (features/security-hardening) - Scenarios: Azure Container Apps, AKS Deployment, Production Observability, Production Troubleshooting - Reference: Container Image, State Backend Selection Fix guide count mismatch and expand EXPECTED_GUIDES, EXPECTED_REFERENCE, EXPECTED_SCENARIOS, and EXPECTED_FEATURES in test/docs-build.test.ts so all 8 new pages are covered and no orphan pages remain. Related to #1564 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/src/navigation.ts | 14 ++++++++++++++ test/docs-build.test.ts | 9 +++++++-- 2 files changed, 21 insertions(+), 2 deletions(-) diff --git a/docs/src/navigation.ts b/docs/src/navigation.ts index 792a779cf..192680ab6 100644 --- a/docs/src/navigation.ts +++ b/docs/src/navigation.ts @@ -92,6 +92,7 @@ export const NAV_SECTIONS: NavSection[] = [ { title: 'Tips & Tricks', slug: 'guide/tips-and-tricks' }, { title: 'Sample Prompts', slug: 'guide/sample-prompts' }, { title: 'Recipes', slug: 'cookbook/recipes' }, + { title: 'Agent Framework Integration', slug: 'guide/agent-framework-integration' }, { title: 'Building Extensions', slug: 'guide/building-extensions' }, { title: 'Building Resilient Agents', slug: 'guide/building-resilient-agents' }, { title: 'Extensibility', slug: 'guide/extensibility' }, @@ -100,6 +101,13 @@ export const NAV_SECTIONS: NavSection[] = [ { title: 'Contributors', slug: 'guide/contributors' }, ], }, + { + title: 'Security', + dir: 'features', + items: [ + { title: 'Security Hardening', slug: 'features/security-hardening' }, + ], + }, { title: 'Scenarios', dir: 'scenarios', @@ -131,6 +139,10 @@ export const NAV_SECTIONS: NavSection[] = [ { title: 'Aspire Dashboard', slug: 'scenarios/aspire-dashboard' }, { title: 'Keep My Squad', slug: 'scenarios/keep-my-squad' }, { title: 'Troubleshooting', slug: 'scenarios/troubleshooting' }, + { title: 'Azure Container Apps', slug: 'scenarios/azure-container-apps' }, + { title: 'AKS Deployment', slug: 'scenarios/aks-deployment' }, + { title: 'Production Observability', slug: 'scenarios/production-observability' }, + { title: 'Production Troubleshooting', slug: 'scenarios/production-troubleshooting' }, ], }, { @@ -143,6 +155,8 @@ export const NAV_SECTIONS: NavSection[] = [ { title: 'SDK Integration', slug: 'reference/integration' }, { title: 'Tools & Hooks', slug: 'reference/tools-and-hooks' }, { title: 'Config', slug: 'reference/config' }, + { title: 'Container Image', slug: 'reference/container-image' }, + { title: 'State Backend Selection', slug: 'reference/state-backend-selection' }, { title: 'Glossary', slug: 'reference/glossary' }, ], }, diff --git a/test/docs-build.test.ts b/test/docs-build.test.ts index cb840883c..68e4ba0d7 100644 --- a/test/docs-build.test.ts +++ b/test/docs-build.test.ts @@ -25,9 +25,9 @@ function docsBuildSkipReason(): string | null { // Expected content directories in src/content/docs/ const EXPECTED_GET_STARTED = ['installation', 'first-session', 'five-minute-start', 'choose-your-interface', 'migration']; -const EXPECTED_GUIDES = ['build-autonomous-agent', 'building-extensions', 'building-resilient-agents', 'contributing', 'contributors', 'extensibility', 'faq', 'github-auth-setup', 'sample-prompts', 'tips-and-tricks']; +const EXPECTED_GUIDES = ['agent-framework-integration', 'build-autonomous-agent', 'building-extensions', 'building-resilient-agents', 'contributing', 'contributors', 'extensibility', 'faq', 'github-auth-setup', 'sample-prompts', 'tips-and-tricks']; -const EXPECTED_REFERENCE = ['cli', 'sdk', 'config', 'api-reference', 'integration', 'tools-and-hooks', 'glossary']; +const EXPECTED_REFERENCE = ['cli', 'sdk', 'config', 'api-reference', 'integration', 'tools-and-hooks', 'glossary', 'container-image', 'state-backend-selection']; const EXPECTED_SCENARIOS = [ 'aspire-dashboard', @@ -55,6 +55,10 @@ const EXPECTED_SCENARIOS = [ 'team-state-storage', 'troubleshooting', 'upgrading', + 'azure-container-apps', + 'aks-deployment', + 'production-observability', + 'production-troubleshooting', ]; const EXPECTED_FEATURES = [ @@ -88,6 +92,7 @@ const EXPECTED_FEATURES = [ 'skills', 'storage-provider', 'squad-rc', + 'security-hardening', 'streams', 'team-setup', 'upstream-inheritance',