From be92e8ace80b8dc30adeebc19fbb19065a2bb2a6 Mon Sep 17 00:00:00 2001 From: brady gaster Date: Thu, 20 Aug 2026 00:47:23 -0700 Subject: [PATCH 1/2] chore(squad): merge decision inbox and summarize agent histories Scribe run captured during the epic-continuation e2e session. Merges nine inbox entries into decisions.md and applies the history summarization gate to six agent histories. Inbox entries merged and cleared: booster-ci-deletion-guard, booster-release-skill-v094, copilot-plan-workflow-ux, copilot-sdlc-workflows, data-restore-dev-main-ancestry, dispatch-enforcement-decision, flight-versioning-policy, procedures-fix-coordinator-inline-dispatch-gate, retro-copilot-git-safety The 167 deletions in decisions.md are deduplication, not data loss: 'CI deletion guard and source tree canary' and 'Copilot git safety rules' each appeared twice, and 'Versioning Policy' / 'Versioning policy' were case-variant duplicates of one entry. booster-continuation-dispatch-inputs.md is deliberately left unmerged -- it landed on dev after this run started and was never in its input set. Known issue, not addressed here: inbox files carry their own H2 sections, which splice in verbatim beneath H3 entries and break heading hierarchy. Pre-existing (dev already has 14 such H2s); the fix belongs in Scribe's merge logic, not in a one-time cleanup. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 26891f18-3f78-4cda-801b-ee668fecae33 --- .squad/agents/booster/history.md | 167 +--- .squad/agents/eecom/history.md | 309 +------ .squad/agents/fido/history.md | 228 +---- .squad/agents/flight/history.md | 190 +--- .squad/agents/pao/history.md | 257 +----- .squad/agents/procedures/history.md | 162 +--- .squad/decisions.md | 868 ++++++++++++++---- .../inbox/booster-ci-deletion-guard.md | 4 - .../inbox/booster-release-skill-v094.md | 35 - .../inbox/copilot-plan-workflow-ux.md | 164 ---- .../decisions/inbox/copilot-sdlc-workflows.md | 45 - .../inbox/data-restore-dev-main-ancestry.md | 100 -- .../inbox/dispatch-enforcement-decision.md | 94 -- .../inbox/flight-versioning-policy.md | 32 - ...es-fix-coordinator-inline-dispatch-gate.md | 45 - .../inbox/retro-copilot-git-safety.md | 4 - 16 files changed, 855 insertions(+), 1849 deletions(-) delete mode 100644 .squad/decisions/inbox/booster-ci-deletion-guard.md delete mode 100644 .squad/decisions/inbox/booster-release-skill-v094.md delete mode 100644 .squad/decisions/inbox/copilot-plan-workflow-ux.md delete mode 100644 .squad/decisions/inbox/copilot-sdlc-workflows.md delete mode 100644 .squad/decisions/inbox/data-restore-dev-main-ancestry.md delete mode 100644 .squad/decisions/inbox/dispatch-enforcement-decision.md delete mode 100644 .squad/decisions/inbox/flight-versioning-policy.md delete mode 100644 .squad/decisions/inbox/procedures-fix-coordinator-inline-dispatch-gate.md delete mode 100644 .squad/decisions/inbox/retro-copilot-git-safety.md diff --git a/.squad/agents/booster/history.md b/.squad/agents/booster/history.md index c1561cb38..3b62aa0a4 100644 --- a/.squad/agents/booster/history.md +++ b/.squad/agents/booster/history.md @@ -1,151 +1,42 @@ -# BOOSTER +# Booster history -> Booster Systems Engineer +Summarized by Scribe on 2026-08-19T13:11:34.130-07:00 because this history exceeded 15KB. +Full pre-summary history archived at `.squad/agents/booster/history-archive-2026-08-19T13-11-34.130-07-00.md`. -## Learnings +## Condensed index -### CI Workflow Audit & Preflight Patterns (2026-03-23 Release Incident) -**Context:** v0.9.0 shipped with broken dependency reference (`file:../squad-sdk` in CLI package.json). Required hotfix. Used incident as opportunity to audit entire CI/CD system. +- Preserved 229 original line(s) in the archive. +- Detected 17 heading(s) and 4 dated reference line(s). +- This file now keeps a compact index plus the most recent tail so active context remains visible. -**Audit findings:** 15 total workflow files. 7 load-bearing (ci, publish, release, preview, promote, insider variants). 7 administrative (triage, assign, labels, heartbeat, docs, link-check). 1 ghost (publish-npm.yml, deleted but GitHub index cached). No duplication. Authorship: 65% Brady, 10% Copilot (v0.9.1 scramble), 25% team. +## Notable retained signals -**Key patterns identified:** +- ### CI Workflow Audit & Preflight Patterns (2026-03-23 Release Incident) +- **Context:** v0.9.0 shipped with broken dependency reference (`file:../squad-sdk` in CLI package.json). Required hotfix. Used incident as opportunity to audit entire CI/CD system. +- **Audit findings:** 15 total workflow files. 7 load-bearing (ci, publish, release, preview, promote, insider variants). 7 administrative (triage, assign, labels, heartbeat, docs, link-check). 1 ghost (publish-npm.yml, deleted but GitHub index cached). No duplication. Authorship: 65% Brady, 10% Copilot (v0.9.1 scramble), 25% team. - Preflight gate (dependency scanning + semver validation) prevents dependency defects - Implicit ordering risk: squad-release and squad-npm-publish both trigger on `release: published` with no explicit job dependency (works but fragile) - Ghost workflow cleanup: GitHub's workflow index caches file names; deletion doesn't immediately invalidate; must wait 15+ minutes or manually refresh - -**Preflight job pattern:** Scans `packages/*/package.json` for: -1. `file:` references (breaks published packages) -2. Invalid semver versions (rejects malformed versions) -Runs before smoke-test and all publish operations. Zero-cost gate (JSON reads only). Clear error messages with remediation instructions. - -### CI Pipeline Status -149 test files, 3,931 tests passing, ~89s runtime. Only failure: aspire-integration.test.ts (needs Docker daemon — pre-existing, expected). publish.yml triggers on `release: published` event with retry logic for npm registry propagation (5 attempts, 15s sleep). - -### Known CI Patterns -SKIP_BUILD_BUMP=1 environment variable intended to prevent version mutation during CI builds. Currently unreliable — bump-build.mjs ignores it in some code paths. NPM_TOKEN must be Automation type (not user token with 2FA) to avoid EOTP errors in publish workflow. - -### Workflow Inventory -9 load-bearing workflows (215 min/month) must stay as GitHub Actions. 5 migration candidates (12 min/month) could move to CLI: sync-labels, triage, assign, heartbeat, validate-labels. - -### Container Smoke Test Patterns -`npm pack` generates tarballs installable in clean containers for pre-publish validation. GitHub Actions containers (node:20-slim, node:22) suitable for smoke tests. No devcontainer config exists yet. Current CI budget: ~227 min/month. Container smoke test adds ~2-5 min per run. Tier 1 smoke test commands: `--version`, `--help`, `doctor`, `status`, `export`. CLI has 31 commands; 15 are user-facing smoke test candidates. cli-command-wiring.test.ts catches unwired commands at build time (issues #224, #236, #237). - -### Smoke Test Gating in Publish Pipeline -Smoke tests now run as a dedicated `smoke-test` job in publish.yml before any npm publish operations. Both publish-sdk and publish-cli jobs depend on smoke-test passing. Prevents publishing broken CLI packages to npm. Smoke test runs `npx vitest run test/cli-packaging-smoke.test.ts` after a full build. Test takes ~30-60s for pack+install validation. - -### CI Pipeline Hardening — March 20, 2026 - -**Changes shipped in commit 6cbabb5 (dev branch):** - -1. **`edited` trigger added** — `pull_request` event types now include `edited`. Previously, retargeting a PR from `main→dev` would not refire CI because the base branch change uses the `edited` event type. Six PRs (#470, #469, #468, #467, #454, #451) were manually close/reopened to compensate. - -2. **Lockfile lint step added** — New step `Lint lockfile for stale workspace entries` runs before `npm ci` in the `test` job. Uses Node inline script to detect any `packages/*/node_modules/@bradygaster/squad-*` entries in `package-lock.json` that have an `https://` resolved URL (indicating a stale nested registry copy shadowing the workspace symlink). Exits with error code + remediation instructions if found. This catches the TypeScript type-mismatch class of failures at the lockfile level, not at build time. - -3. **Default branch changed to `dev`** — Repo default branch switched from `main` to `dev` via GitHub API. Community PRs now naturally target `dev`. - -**Pattern confirmed:** The `edited` event gap was the exact reason retargeted PRs were not getting CI runs. Any future PR base-branch change will now trigger a fresh CI run automatically. - -### CI Failure Pattern Analysis — March 15, 2026 -Analyzed 20 CI runs from March 15. Identified 3 distinct failure categories: - -**1. TypeScript Build Failures — SDK/CLI Type Mismatches (Most Critical)** +- ### CI Pipeline Status +- ### Known CI Patterns +- SKIP_BUILD_BUMP=1 environment variable intended to prevent version mutation during CI builds. Currently unreliable — bump-build.mjs ignores it in some code paths. NPM_TOKEN must be Automation type (not user token with 2FA) to avoid EOTP errors in publish workflow. +- ### Workflow Inventory +- 9 load-bearing workflows (215 min/month) must stay as GitHub Actions. 5 migration candidates (12 min/month) could move to CLI: sync-labels, triage, assign, heartbeat, validate-labels. +- `npm pack` generates tarballs installable in clean containers for pre-publish validation. GitHub Actions containers (node:20-slim, node:22) suitable for smoke tests. No devcontainer config exists yet. Current CI budget: ~227 min/month. Container smoke test adds ~2-5 min per run. Tier 1 smoke test commands: `--version`, `--help`, `doctor`, `status`, `export`. CLI has 31 commands; 15 are user-facing smoke test candidates. cli-command-wiring.test.ts catches unwired commands at build time (issues #224, #236, #237). +- Smoke tests now run as a dedicated `smoke-test` job in publish.yml before any npm publish operations. Both publish-sdk and publish-cli jobs depend on smoke-test passing. Prevents publishing broken CLI packages to npm. Smoke test runs `npx vitest run test/cli-packaging-smoke.test.ts` after a full build. Test takes ~30-60s for pack+install validation. +- ### CI Pipeline Hardening — March 20, 2026 +- 1. **`edited` trigger added** — `pull_request` event types now include `edited`. Previously, retargeting a PR from `main→dev` would not refire CI because the base branch change uses the `edited` event type. Six PRs (#470, #469, #468, #467, #454, #451) were manually close/reopened to compensate. +- 2. **Lockfile lint step added** — New step `Lint lockfile for stale workspace entries` runs before `npm ci` in the `test` job. Uses Node inline script to detect any `packages/*/node_modules/@bradygaster/squad-*` entries in `package-lock.json` that have an `https://` resolved URL (indicating a stale nested registry copy shadowing the workspace symlink). Exits with error code + remediation instructions if found. This catches the TypeScript type-mismatch class of failures at the lockfile level, not at build time. +- **Pattern confirmed:** The `edited` event gap was the exact reason retargeted PRs were not getting CI runs. Any future PR base-branch change will now trigger a fresh CI run automatically. +- ### CI Failure Pattern Analysis — March 15, 2026 +- Analyzed 20 CI runs from March 15. Identified 3 distinct failure categories: - 7+ consecutive failures on `squad/fix-ci-build` branch (14:00-14:11 UTC) -- Root cause: Stale nested SDK entry in package-lock.json causing TypeScript module resolution errors -- Error: "Module '@bradygaster/squad-sdk' has no exported member 'listRoles'" (and 6 other missing exports) -- Impact: Build failures blocked all PRs attempting to fix roles/cast features -- Fix: Removing stale lockfile entry resolved TypeScript resolution - Pattern: Workspace dependency mismatches not caught until CI build phase - -**2. Documentation Quality Gate Failures — New Validation Rules** +- **2. Documentation Quality Gate Failures — New Validation Rules** - 3 failures on `squad/docs-quality-ci` branch (14:32, 15:26, 15:51 UTC) -- Issue 1: Broken anchor link `../guide.md#troubleshooting` (anchor doesn't exist) -- Issue 2: Spell check failure for username "benleane" in notifications.md (not in cspell dictionary) - Impact: New docs-quality job blocked merges when introducing new validation gates -- Pattern: Adding stricter CI gates without pre-validation of existing content creates immediate failures - -**3. Test Failures — ES Module Migration Side Effects (Legacy)** -- 1 failure on main branch (13:59 UTC) — "deleted images" commit -- Root cause: 8 test files using `require()` in ES module context -- Error: "require is not defined in ES module scope" (node:test imports) -- Impact: Old test files incompatible with `"type": "module"` in package.json -- Pattern: Incomplete ESM migration left test files in CommonJS syntax - -**Key Observations:** -- **Failure clusters**: Multiple consecutive failures trying to fix same root issue (TypeScript build: 7 attempts, docs-quality: 3 attempts) -- **Validation timing**: New validation gates (docs-quality CI) introduced without pre-testing against current codebase state -- **Workspace complexity**: Monorepo TypeScript workspace dependencies prone to lockfile staleness -- **Branch health**: dev branch had 2 failures (last failure: spell check), currently yellow/orange status - -**Recommended CI Improvements:** -1. Pre-merge lockfile validation check (detect stale nested dependencies) -2. Docs validation dry-run before adding new quality gates -3. TypeScript workspace reference health check (catch SDK/CLI type mismatches early) -4. Better failure grouping/attribution in CI UI (distinguish "new gate" vs "regression") -5. Spell check dictionary maintenance workflow (easier to add known-good usernames/terms) - -### CI Workflow Audit — March 23, 2026 - -**Status:** Conducted full audit of 15 workflow files. Brady's perception ("complete nightmare, 12,000 workflows") is not accurate — the codebase is lean, well-organized, and 99% authored by Brady (bradygaster + Copilot). - -**Key Findings:** -- **Total workflows:** 15 (7 load-bearing core, 7 admin/automation, 1 ghost) -- **Authorship:** bradygaster 46 commits (65%), Copilot 7 (10%), team 17 (24%) -- **v0.9.1 Scramble:** Copilot made 4 commits on 2026-03-23 trying to work around GitHub platform bug (workflow_dispatch returns 422 after file renames/deletes) -- **Ghost file identified:** `publish-npm.yml` (deleted but still in GitHub's workflow cache) → requires manual deletion via API -- **Zero duplication:** Each workflow has clear, non-overlapping responsibility -- **One optional cleanup:** `ci-rerun.yml` (useful but not essential) -**Release Pipeline Quality:** -- Core pipeline (squad-ci → squad-release → squad-npm-publish → insider-*) is solid -- Smoke tests run before any npm publish (good safety gate) -- Implicit ordering works but fragile (squad-npm-publish depends on release: published event) - -**Triage Automation Quality:** -- Label routing (squad-triage, squad-issue-assign, squad-label-enforce) well-integrated -- Ralph heartbeat has cron disabled (event-driven only) -- Works correctly with @copilot assignment - -**Recommendation:** Delete ghost publish-npm.yml file, optionally keep ci-rerun for fork PR debugging, keep everything else. CI health is good. - -**Report written to:** `.squad/decisions/inbox/booster-ci-audit.md` - -### CI Cleanup & Hardening — Post-Audit - -**Changes shipped:** - -1. **Ghost workflow disabled** — `publish-npm.yml` (workflow ID 250121956) disabled via GitHub API (`PUT /actions/workflows/{id}/disable`). GitHub doesn't support DELETE on workflow entries; disable is the permanent fix. - -2. **Pre-publish `preflight` job added** to `squad-npm-publish.yml`: - - Scans ALL `packages/*/package.json` for `file:` references across all dependency sections (dependencies, devDependencies, optionalDependencies, peerDependencies) - - Validates all package versions are valid semver - - Runs BEFORE smoke-test and all publish jobs — blocks the entire pipeline if violations found - - This is the gate that would have caught the v0.9.1 incident - -3. **Smoke test enhanced** — Added `npm pack --dry-run` validation step for both SDK and CLI packages before the vitest smoke tests run - -4. **ci-rerun.yml retained** — Added purpose documentation comment. Still useful for fork PR re-testing and infrastructure flake recovery. - -5. **YAML fix** — Quoted `file:` in step names that were causing YAML parse ambiguity (both new and pre-existing) - -**Pipeline dependency chain:** `preflight → smoke-test → publish-sdk → publish-cli` - -### Release Process Skill Update — v0.9.4 Learnings (2026-04-25) - -Updated both release-process skill files (`.squad/skills/release-process/SKILL.md` and `.copilot/skills/release-process/SKILL.md`) with critical learnings from the v0.9.4 release session. Added 5 new Known Gotchas, a full `v0.9.4 Incident Learnings` section, GITHUB_TOKEN propagation workaround, CHANGELOG/root-package.json validation rules, lockfile integrity fix documentation, local dev recovery steps, and cross-references between skill files. Source PRs: #1042, #1043, #1044. - -### CI Cleanup — Issue #1000 (2026-04-17) - -**Changes shipped in PR #1001:** - -1. **Deleted `ci-rerun.yml`** — Redundant fork PR workflow with 100% failure rate (5/5 runs). GitHub's native "Approve and Run" handles fork PR CI. Removed reference from `setup-squad-node` comment header. - -2. **Streamlined `squad-ci.yml`** — 852 → 585 lines, 9 → 6 jobs: - - **Merged** `exports-map-check` + `export-smoke-test` → single `sdk-exports-validation` job (saves one runner boot, deduplicates checkout/setup/change-detection) - - **Folded** `publish-policy` + `scope-check` into `policy-gates` as additional gate steps (saves two runner boots) - - **Added** `workflows` output to `changes` path filter (policy-gates now properly skips on docs-only PRs) - - **Trimmed** verbose local-testing instruction comments and skip-labels reference block - - **Preserved** all genuine safety checks — no gates removed, only consolidated +## Recent preserved tail **Key decisions:** - Merging exports-map-check + export-smoke-test is safe because they share identical prerequisites (SDK change detection, feature flags, skip labels) and both only need SDK build @@ -159,7 +50,7 @@ Updated both release-process skill files (`.squad/skills/release-process/SKILL.m ### Workflow Shellcheck SC2086 Fix + Actionlint CI Gate (2026-07-29T17:11:56+10:00) -**Context:** Issue #1556 (bradygaster/squad) reported SC2086 failures in downstream repos using actionlint after `squad upgrade`. The unquoted `>> $GITHUB_OUTPUT` redirects in `squad-heartbeat.yml` were the reported trigger; audit revealed matching issues in `squad-repo-health.yml` and `squad-ci.yml` too. +**Context:** Issue #1556 (bradygaster/squad) reported SC2086 failures in other repos using actionlint after `squad upgrade`. The unquoted `>> $GITHUB_OUTPUT` redirects in `squad-heartbeat.yml` were the reported trigger; audit revealed matching issues in `squad-repo-health.yml` and `squad-ci.yml` too. **Changes shipped:** @@ -223,3 +114,7 @@ Updated both release-process skill files (`.squad/skills/release-process/SKILL.m **Validation:** `bash -n` passes on the new run block. Self-linting property holds — actionlint + shellcheck will lint this exact `run:` block on the next CI run, catching any quoting or syntax issues we introduce. Amended and force-pushed to `serbrech/squad` as a single commit. +## 📌 Team update — 2026-08-19T13:11:34.130-07:00 + +Post-e2e follow-up triage recorded Booster findings D and F. Finding F confirmed `protected-files: request_review` is incompatible with signed create-pull-request writes that touch protected files; `fallback-to-issue` is the safe fail-closed path. Finding D confirmed the `slash_command` + `bots:` concurrency warning is real but narrow and does not block the continuation e2e because the continuation hop uses `workflow_dispatch`. + diff --git a/.squad/agents/eecom/history.md b/.squad/agents/eecom/history.md index 9fb938d58..07eb1d11f 100644 --- a/.squad/agents/eecom/history.md +++ b/.squad/agents/eecom/history.md @@ -1,289 +1,42 @@ -# EECOM +# Eecom history -> Environmental, Electrical, and Consumables Manager +Summarized by Scribe on 2026-08-19T13:11:34.130-07:00 because this history exceeded 15KB. +Full pre-summary history archived at `.squad/agents/eecom/history-archive-2026-08-19T13-11-34.130-07-00.md`. -## Core Context +## Condensed index -CLI entry point (`cli-entry.ts`) is the central router for 30+ commands. `safeTimestamp()` utility provides Windows-safe filenames (colons → hyphens). CastingEngine augments LLM casting with curated names — augment, not replace. `npm pack` produces complete installable tarball (~275KB). ESM module patch required for Node 24+ strict mode (@github/copilot-sdk@0.1.32 missing .js extension). +- Preserved 367 original line(s) in the archive. +- Detected 39 heading(s) and 26 dated reference line(s). +- This file now keeps a compact index plus the most recent tail so active context remains visible. -## Recent Learnings +## Notable retained signals -### Template Brady contamination fix (#977) (2026-05-01) -Replaced all hardcoded "Brady" in template examples with generic `{user}`/`{name}` placeholders. Canonical sources: `.squad-templates/squad.agent.md` and `.copilot/skills/init-mode/SKILL.md`. Template sync only covers `.squad-templates/`; init-mode SKILL.md package copies required manual edits. Key distinction: only files copied to user repos were changed; Brady references in project docs are legitimate content. - -### PR #942 rebase — cherry-pick from insider-based fork branch (2026-04-12) -When cherry-picking from an insider-based branch to dev, expect modify/delete conflicts for files that only exist on insider. Always verify the base assumptions of each change — imports referencing insider-only modules must be dropped or adapted. Opened #963 as clean replacement, closed #942. - -### archiveDecisions() count-based fallback (#626) (2025-07-24) -Added count-based fallback when all `###` entries are <30 days old but file is >20KB. Separates recent entries into dated vs undated, sorts dated by age, keeps entries under threshold budget. **Rule:** Undated entries are always preserved (foundational directives). When a function has an early-return optimization, always consider whether the condition that triggered it can still be true when the early-return fires. - -### node:sqlite Hard-Fail Fix (#502) (2026-03-21) -Replaced soft-warn with synchronous version check + `process.exit(1)` for Node <22.5.0. Added `checkNodeVersion()` to `squad doctor`. Corrected `engines.node` to `>=22.5.0` in all package.json files. **Pattern:** Always confirm `git branch` before editing files — edits don't follow you to a new branch. - -### Personal Squad Init via npx (#576) (2026-03-23) -`init --global` now calls `ensurePersonalSquadDir()` after global init. Added idempotent `ensurePersonalSquadDir()` to SDK resolution.ts. `resolveGlobalSquadPath()` returns the container; `ensurePersonalSquadDir()` creates the `personal-squad/` subdirectory the rest of the system looks for. - -## Historical Learnings Summary (condensed) - -- **Loop command (#767):** For interactive/long-running child processes, always attach `.on('data')` listeners for real-time output. When using `node:fs` mocked in tests, use `vi.importActual('node:fs')` in `beforeAll` to get real filesystem access. teamRoot must derive from `detectSquadDir().path` not `workTreeRoot` in worktree scenarios. -- **Init scaffolding (no-remote, casting files) (#579):** Three execFileSync calls for git remote needed `stdio: ['pipe','pipe','pipe']` to suppress stderr. Init flow creates .squad/casting/ but never populated it — added scaffolding block. Pattern: execFileSync inside try/catch still leaks stderr without piped stdio. -- **CLI Version Subcommand:** `cmd === 'version'` added to existing `--version`/`-v` condition in cli-entry.ts. No separate command file needed for trivial inline handlers. -- **Privacy scrub messaging + EPERM + gitignore parent coverage (#549):** `ensureGitattributes` catches EPERM/EACCES, returns [] with console.warn. `ensureGitignore` skips entries with parent already covered. Footer shows "Privacy scrub applied" vs "Preserves user state" based on whether scrub ran. -- **Economy Mode (#500):** Layer 3 modifier only — never downgrades Layers 0-2 (user intent). `ECONOMY_MODEL_MAP` + `applyEconomyMode()` + CLI `squad economy on|off` + `--economy` flag. 34 tests. -- **Rate Limit UX (#464):** `rateLimitGuidance()` + `.squad/rate-limit-status.json` + `checkRateLimitStatus()` in doctor. Import `RateLimitError` from `@bradygaster/squad-sdk/adapter/errors` (subpath export, not main barrel). -- **CastingEngine CLI Integration (#342):** CastingEngine.castTeam() was never called in CLI flow. `augmentWithCastingEngine()` in cast.ts replaces LLM names with engine characters for recognized universes. Import from `@bradygaster/squad-sdk/casting` (not main barrel). 9 AgentRole enum values, not 6. +- Replaced all hardcoded "Brady" in template examples with generic `{user}`/`{name}` placeholders. Canonical sources: `.squad-templates/squad.agent.md` and `.copilot/skills/init-mode/SKILL.md`. Template sync only covers `.squad-templates/`; init-mode SKILL.md package copies required manual edits. Key distinction: only files copied to user repos were changed; Brady references in project docs are legitimate content. +- ### PR #942 rebase — cherry-pick from insider-based fork branch (2026-04-12) +- When cherry-picking from an insider-based branch to dev, expect modify/delete conflicts for files that only exist on insider. Always verify the base assumptions of each change — imports referencing insider-only modules must be dropped or adapted. Opened #963 as clean replacement, closed #942. +- ### archiveDecisions() count-based fallback (#626) (2025-07-24) - **Cross-platform filename & config fixes (#348, #356):** Use centralized `safeTimestamp()` everywhere. Removed machine-specific `teamRoot` from config.json (computed at runtime via `git rev-parse`). - **PR #427 cross-fork rebase:** When rebasing with git worktrees, always create a dedicated worktree for complex operations. In rebase context, "ours" = upstream, "theirs" = your branch. Use `git worktree list` to diagnose unexpected branch switching. -- **SDK Init Flow Deep Dive:** Critical gap: squad.config.ts never updated after auto-cast. CastingEngine exists but is never called. Roadmap: sync utility → Ralph fixes → CastingEngine integration → hire/remove commands. -- **Adoption Tracking Tier 1:** Moved `.squad/adoption/` → `.github/adoption/`. Aggregate metrics only — never publish individual repo lists without opt-in. - **PR #483 (platform-adapter timeout):** `{ ...EXEC_OPTS, timeout: 3_000 }` pattern for external CLI calls that might hang. Existing catch block with fallback handles timeout errors. - **PR #480 (history race condition):** Three-layer defense: async mutex, atomic file operations (write-then-rename), 14 tests. - **PR #486 (SIGINT handling):** Two layers: parent SIGINT handler + child process cleanup (kill children, close handles, flush buffers). 22 tests. -## Learnings - -### Template Brady contamination fix (#977) (2026-05-01) - -**Context:** Template files (squad.agent.md, init-mode/SKILL.md) contained hardcoded "Brady" examples in greetings, routing examples, and comments. LLMs treated these as patterns, greeting every user as "Brady" regardless of their actual `git config user.name`. - -**Fix:** Replaced all hardcoded "Brady" in template examples with generic `{user}` / `{name}` placeholders. Canonical sources: `.squad-templates/squad.agent.md` and `.copilot/skills/init-mode/SKILL.md`. Template sync (`node scripts/sync-templates.mjs`) propagated squad.agent.md to `.github/agents/` but did NOT sync init-mode SKILL.md to package templates — those required manual edits in both `packages/squad-cli/templates/skills/init-mode/SKILL.md` and `packages/squad-sdk/templates/skills/init-mode/SKILL.md`. - -**Key distinction:** Only template files that get copied to user repos were changed. Brady references in project docs (history-hygiene, release-process, humanizer, architectural-proposals, reskill) are legitimate content about the project founder and were left unchanged. - -**Pattern:** When fixing template contamination, verify which files are covered by `sync-templates.mjs` and which require manual propagation. The init-mode SKILL.md lives in `.copilot/skills/` (not `.squad-templates/`), so sync doesn't touch its package copies. - -### PR #942 rebase — cherry-pick from insider-based fork branch (2026-04-12) - -**Context:** PR #942 from tamirdresher's fork was retargeted from `insider` to `dev`, causing 29 files in the diff when only 3 commits (4 files relevant to dev) were the actual fix. Cherry-picked the 3 fix commits onto a clean `squad/942-rebase-type-safety` branch from dev, resolving conflicts where insider-only files (skill.ts, cross-package-exports.test.ts) didn't exist on dev. Dropped the `escapeYamlValue` import and APM YAML generation function from init.ts since skill.ts doesn't exist on dev. Opened #963 as the clean replacement, closed #942. - -**Key lesson:** When cherry-picking from an insider-based branch to dev, expect modify/delete conflicts for files that only exist on insider. Always verify the base assumptions of each change — imports referencing insider-only modules must be dropped or adapted. - -### Loop command: second-round review fixes (#767) (2025-07-26) - -**Context:** Three Copilot review comments on PR #767: (1) `teamRoot` was set to `workTreeRoot` but `.squad/` may live in the main checkout when running inside a git worktree — should derive from `detectSquadDir().path`, (2) `generateLoopFile()` hardcoded the full loop.md scaffold inline, duplicating `templates/loop.md`, (3) docs said `gh` was optional but code hard-requires `gh copilot` unless `--agent-cmd` is passed. - -**Fixes:** -1. **teamRoot:** Changed `const teamRoot = workTreeRoot` to `path.dirname(squadDirInfo.path)` — `.squad/`-relative operations now always use the directory where `.squad/` was actually found. -2. **Template dedup:** Replaced 48-line hardcoded template with `readFileSync` reading from `templates/loop.md`. Used `import.meta.url` + `fileURLToPath` to resolve the path from the compiled file (3 levels up to package root). Created `packages/squad-cli/templates/loop.md` since it was missing from the CLI package's templates dir. -3. **Docs:** Updated prerequisites to state `gh` + `gh copilot` are required by default, with `--agent-cmd` as the escape hatch. - -**Test impact:** Tests mock `node:fs` globally, so `readFileSync` in `generateLoopFile()` needed mock setup. Added `beforeAll` using `vi.importActual('node:fs')` to read the REAL template file, then `beforeEach` to set the mock return value. This keeps tests validating the actual template content. - -**Pattern:** When reading template files in code that has mocked `node:fs` tests, use `vi.importActual('node:fs')` in `beforeAll` to get real filesystem access for loading test fixtures. - -### Loop command: streaming output, worktree CWD, docs alignment (#767) (2025-07-25) - -**Context:** Copilot code review on PR #767 flagged three issues in the loop command: (1) `execFile` buffered stdout/stderr but never printed it — users saw no Copilot output during loop rounds, (2) `loop.md` was resolved relative to `dest` but execution used `teamRoot` (derived from `.squad/` parent), creating a CWD mismatch in worktree scenarios, (3) docs said `description` defaults to `""` but code uses `'Squad Loop'`. - -**Fixes:** -1. **Streaming:** Added `.on('data')` listeners to `currentChild.stdout` and `currentChild.stderr` after `execFile` spawn. Since output streams in real-time, the callback no longer re-writes buffered stdout/stderr on error (would duplicate). -2. **Worktree CWD:** Introduced `workTreeRoot = path.resolve(dest)` and set `teamRoot = workTreeRoot`. Both file resolution and execution CWD now use the same root. -3. **Docs:** Updated `docs/src/content/docs/features/loop.md` description default from `""` to `"Squad Loop"`. - -**Key file:** `packages/squad-cli/src/cli/commands/loop.ts` — `runLoop()` entry point (~line 302), `executeRound()` inner function (~line 427). - -**Pattern:** When using Node's `execFile` for interactive/long-running child processes, always attach stream listeners for real-time output. The callback's `stdout`/`stderr` args are the same buffered content — writing both duplicates output. - -### archiveDecisions() count-based fallback (#626) (2025-07-24) - -**Context:** `archiveDecisions()` in `packages/squad-cli/src/cli/core/nap.ts` silently returned `null` when all `###` entries were <30 days old (`old.length === 0`), even if the file was well over 20KB. Active projects generating many decisions per session could hit 145KB+ — 35K tokens burned per agent spawn. - -**Fix:** Added a count-based fallback after the age-based split. When `old.length === 0` and total file size exceeds `DECISION_THRESHOLD` (20KB), the fallback separates recent entries into dated vs undated, sorts dated by age (most recent first), keeps entries that fit under the threshold budget, and archives the rest. Undated entries are always preserved — they are foundational directives per Procedures' guidance. - -**Key design choices:** -1. Undated entries (`daysAgo === null`) are never archived by the count-based fallback. They stay in `recent`. -2. Budget calculation accounts for header + undated entries + kept dated entries to guarantee the result fits under 20KB. -3. Entries are re-sorted into original document order after the split, so the output file preserves heading sequence. - -**Tests:** Added 4 adversarial tests — 50 all-today entries >20KB, mixed dated/undated preservation, under-threshold no-op, exact-threshold boundary case. - -**Pattern:** When a function has an early-return optimization (`if (old.length === 0) return null`), always consider whether the condition that triggered the function call (file size > threshold) can still be true when the early-return fires. If so, the early-return is a silent failure. - -### Init scaffolding: casting dir + no-remote stderr (#579) (2025-07-18) - -**Context:** `squad init` in a fresh `git init` repo (no remote) printed `error: No such remote 'origin'` to stderr and `squad doctor` reported `casting/registry.json` missing. Two independent bugs in `packages/squad-sdk/src/config/init.ts`. - -**Fix 1 — Stderr leak:** Three `execFileSync('git', ['remote', 'get-url', 'origin'])` calls in `initSquad()` were missing `stdio: ['pipe','pipe','pipe']`. The try/catch caught the error but git's stderr still leaked to the console. Added stdio piping to all three call sites (lines ~713, ~732, ~1039). - -**Fix 2 — Missing casting files:** The init flow created the `.squad/casting/` directory but never populated it. Added a scaffolding block after directory creation that copies `casting-policy.json`, `casting-registry.json`, and `casting-history.json` from SDK templates (with inline fallbacks). Respects `skipExisting` — never overwrites user files. - -**Pattern:** When calling `execFileSync` for a git command inside a try/catch, always add `stdio: ['pipe','pipe','pipe']` to suppress stderr. The catch prevents a crash, but without piped stdio the error message still prints to the user's terminal. - -### CLI Version Subcommand Pattern (2026-03-23 Release Incident) -**Context:** `squad version` returned "Unknown command: version" even though `squad --version` and `squad -v` worked fine. Classic "unwired command" bug but for a flag-to-subcommand gap rather than a missing import. - -**Pattern:** When a CLI flag works (`--foo`) but the equivalent subcommand doesn't (`foo`), the fix is almost always a single condition addition in `cli-entry.ts`. No separate command file needed for trivial handlers — inline alongside the flag handler. Added `cmd === 'version'` to the existing `--version`/`-v` condition. Also added `version` to help text command list. - -**Why inline works:** Trivial handlers that just print a value don't warrant their own module. Same output, same code path — no reason to split. Avoids adding a file the wiring test would require an import for. Precedent: `help` is also handled inline. - -### `squad version` subcommand (2026-07-15) - -**Context:** Running `squad version` returned "Unknown command: version" because the subcommand was never routed in `cli-entry.ts`, even though `--version` and `-v` flags worked fine. Classic "unwired command" bug class, but for a flag-to-subcommand gap rather than a missing import. - -**Fix:** Added `cmd === 'version'` to the existing `--version`/`-v` condition in `cli-entry.ts` (line ~130). Also added `version` to the help text command list. No new file in `cli/commands/` needed — this is a trivial inline handler, same as `--version`. The wiring test is unaffected since there's no separate command file. - -**Pattern:** When a CLI flag (`--foo`) works but the equivalent subcommand (`foo`) doesn't, the fix is almost always a single condition addition in `cli-entry.ts`. No separate command file needed for trivial handlers. - -### Privacy scrub messaging + EPERM + gitignore parent coverage (#549) (2026-07-14) - -**Context:** Upgrade footer message always said "Preserves user state" even when the email privacy scrub had run — a direct contradiction of what just happened. Two related issues in the same function: EPERM on read-only `.gitattributes` would crash the upgrade, and `.gitignore` would add redundant entries already covered by parent paths (e.g. `.squad/log/` when `.squad/` was already present). - -**Fix:** -1. `upgrade.ts` — `ensureGitattributes` catches EPERM/EACCES and returns `[]` with a console.warn, graceful degradation. -2. `upgrade.ts` — `ensureGitignore` skips an entry when any existing line is a parent prefix of it. -3. `upgrade.ts` — Footer logic checks whether the email scrub actually ran; shows "Privacy scrub applied" or "Preserves user state" accordingly. -4. `test/cli/upgrade.test.ts` — Added EPERM test using `chmodSync` (fix: `chmodSync` was missing from the `fs` import — added it). - -**Pattern:** When adding a new fs function to a test, always verify the named import list at the top of the test file. Missing named imports from `'fs'` produce `ReferenceError` at runtime, not at type-check time (if the test file isn't part of the main tsconfig). - -📌 **Team update (2026-03-22T09-35Z — Wave 1):** Economy mode fully implemented: ECONOMY_MODEL_MAP + resolveModel() integration in SDK, `squad economy on|off` CLI command, `--economy` flag, 34 tests passing. PR #504 open for review. Soft dependency: #464 rate limit UX should offer economy mode as recovery. Next: Phase 1 of ambient personal squad (T1–T5, T19) — ready to start immediately after merging current work. Procedures wrote governance proposals for squad.agent.md — awaiting Flight review. -### Rate Limit UX (#464) (2026-03-20) - -**Context:** Users hitting Copilot rate limits saw generic "Something went wrong processing your message." Squad hid the actual error. `squad doctor` reported nothing — useless to diagnose. - -**Root cause:** The catch block in `shell/index.ts` line ~1119 always emitted `genericGuidance()` unless `SQUAD_DEBUG=1`. Rate limit errors never got special treatment despite `RateLimitError` existing in `adapter/errors.ts`. - -**Fix:** -1. `error-messages.ts` — Added `rateLimitGuidance({ retryAfter?, model? })` and `extractRetryAfter(message)` utilities. Rate limit guidance shows clear message + recovery options (retry time, `squad economy on`, config.json model override). -2. `shell/index.ts` — Catch block now detects rate limits via `instanceof RateLimitError` OR regex on the raw message. Writes `.squad/rate-limit-status.json` on detection. -3. `doctor.ts` — Added `checkRateLimitStatus()` check. Reads status file and warns if rate limit was recent. -4. `test/error-messages.test.ts` — Added 11 new tests covering `rateLimitGuidance` and `extractRetryAfter`. - -**Pattern:** Rate limit status written to `.squad/rate-limit-status.json` as `{ timestamp, retryAfter, model, message }`. Doctor reads it on next run. File is never deleted automatically — doctor marks it `pass` when > 4h stale. - -**Import path for `RateLimitError`:** `@bradygaster/squad-sdk/adapter/errors` (subpath export, not in main barrel). - -**PR:** #464 fix — squad/464-rate-limit-ux - -### CLI Entry Point Architecture -cli-entry.ts is the central router for ~30+ CLI commands using dynamic imports (lazy-loading). Commands are routed via if-else blocks. Has a recurring "unwired command" bug class — implementations exist in cli/commands/ but aren't routed in cli-entry.ts. The cli-command-wiring.test.ts regression test catches this by verifying every .ts file in cli/commands/ is imported. - -### ESM Runtime Patch -Module._resolveFilename interceptor in cli-entry.ts (lines 47-54) patches broken ESM import in @github/copilot-sdk@0.1.32 (vscode-jsonrpc/node missing .js extension). Required for Node 24+ strict ESM enforcement. Works on npx cache hits where postinstall scripts don't run. - -### Lazy Import Pattern -All command imports use `await import('./cli/commands/xxx.js')` to minimize startup time. Copilot SDK is lazily loaded only when shell is invoked. All .js extensions required for Node 24+ strict ESM. - -### CLI Packaging & Distribution -`npm pack` produces a complete, installable tarball (~275KB packed, 1.2MB unpacked). Package includes dist/, templates/, scripts/, README.md per package.json "files" field. Postinstall script (patch-esm-imports.mjs) patches @github/copilot-sdk for Node 24+ compatibility. Tarball can be installed locally (`npm install ./tarball.tgz`) and commands execute via `node node_modules/@bradygaster/squad-cli/dist/cli-entry.js`. Both squad-cli and squad-sdk must be installed together — cli depends on sdk with "*" version specifier. All 27+ CLI commands are lazy-loaded at runtime; `--help` validates command routing without executing full logic. - -### Packaging Smoke Test Strategy -test/cli-packaging-smoke.test.ts validates the packaged artifact (not source). Uses npm pack + install in temp dir + command routing verification. Commands are expected to fail (no .squad/ dir) — test verifies routing only (no "Unknown command", no MODULE_NOT_FOUND for the command itself). Exception: node-pty is an optional dependency for the `start` command and MODULE_NOT_FOUND for node-pty is allowed. Windows cleanup requires retry logic due to EBUSY errors — use rmSync with maxRetries + retryDelay options, wrap in try/catch to fail silently since tests have passed. - -### v0.8.24 Release Readiness Audit -CLI completeness audit (2026-03-08) confirmed: 26 primary commands routed in cli-entry.ts, all present in smoke test. 4 aliases (watch→triage, workstreams→subsquads, remote-control→rc, streams→subsquads). 3 aliases tested, 1 untested ("streams"). Packaging verified: dist/, templates/, scripts/, README.md in tarball; bin entry points to dist/cli-entry.js; postinstall script included and working. All 32 smoke tests pass. Package.json files array correct. npm pack output shows 318 files, 275KB packed. No missing command implementations. Optional dep (node-pty) handled correctly. Only gap: "streams" alias not in smoke test (routed correctly but test coverage incomplete). Confidence: 95% — all critical paths covered, minor alias test gap non-blocking. - -📌 **Team update (2026-03-08T21:18:00Z):** FIDO + EECOM released unanimous GO verdict for v0.8.24. Smoke test approved as release gate. FIDO confirmed 32/32 pass + publish.yml wired correctly. EECOM confirmed 26/26 commands + packaging complete (minor gap: "streams" alias untested, non-blocking). - -### Cross-Platform Filename and Config Fixes (#348, #356) (2026-03-15T05:30:00Z) - -**Context:** Two cross-platform bugs broke Squad on Windows: (1) log filenames contained colons in ISO 8601 timestamps (illegal on Windows), (2) `.squad/config.json` contained absolute machine-specific `teamRoot` path. - -**Investigation:** -- Searched SDK for all timestamp usage in filenames — found `safeTimestamp()` utility already existed but wasn't consistently used -- `comms-file-log.ts` (line 32) used inline `toISOString().replace(/:/g, '-')` instead of utility -- `init.ts` (line 612) wrote absolute `teamRoot` to config.json on every init -- Session-store already used `safeTimestamp()` correctly (line 71) - -**Fixes:** -1. **Bug #348:** Updated `comms-file-log.ts` to import and use `safeTimestamp()` utility instead of inline timestamp formatting -2. **Bug #356:** Removed `teamRoot` field from config.json (can be computed at runtime via `git rev-parse --show-toplevel`) -3. Updated live `.squad/config.json` in repo to remove machine-specific path - -**Pattern:** Centralized timestamp formatting in `safeTimestamp()` utility (replaces colons + truncates milliseconds). Windows-safe format: `2026-03-15T05-30-00Z` instead of `2026-03-15T05:30:00.123Z`. - -**Test Impact:** All 150 tests pass. Communication adapter test doesn't validate specific filename format (structural test, not behavioral). - -**PR:** #404 opened targeting dev. - -### CastingEngine CLI Integration (#342) (2026-03-15T11:20:00Z) - -**Context:** CastingEngine class (Issue #138, M3-2) existed in SDK with curated universe templates (The Usual Suspects, Ocean's Eleven) but was completely bypassed during `squad init`. LLM picked arbitrary names, and charter generation used regex-based `personalityForRole()` instead of template backstories. - -**Investigation:** -- CastingEngine.castTeam() was never called in CLI flow -- coordinator.ts buildInitModePrompt() let LLM pick any universe without guidance -- cast.ts generateCharter() used fallback personality logic instead of engine data -- SDK exports two AgentRole types: broad one in casting-engine.ts, restrictive one in runtime/constants.ts - -**Integration Strategy (Augment, Not Replace):** -- LLM still proposes roles and team composition (the beloved casting experience) -- CastingEngine augments with curated names when universe is recognized -- Mapping: "The Usual Suspects" → 'usual-suspects', "Ocean's Eleven" → 'oceans-eleven' -- Unrecognized universes (Matrix, Alien, etc.) preserve LLM's arbitrary names - -**Implementation:** -1. Added `augmentWithCastingEngine()` in cast.ts to replace LLM names with engine characters -2. Updated coordinator prompt to suggest preferred universes (Usual Suspects, Ocean's Eleven) -3. Extended `generateCharter()` to use engine personalities/backstories when available -4. Attached `_personality` and `_backstory` to CastMember objects for charter generation -5. Role mapping: CLI role strings → engine AgentRole enum (lead, developer, tester, etc.) - -**Type Import Pattern:** -- Import CastingEngine from `@bradygaster/squad-sdk/casting` (not main barrel export) -- Use casting-engine.ts AgentRole type (9 roles) not runtime/constants.ts (6 roles) -- Partial mapping: unmapped roles log warning and skip engine casting - -**Tests:** -- Created test/casting-engine-integration.test.ts (5 tests, all pass) -- Validates augmentation for both universes, case-insensitive matching, fallback behavior -- All 45 existing cast-parser/casting tests still pass - -**PR:** #417 opened targeting dev. - - -### PR #427 Cross-Fork Rebase (2026-03-15T21:00:00Z) - -**Context:** PR #427 (PAO external communications Phase 1) conflicted with upstream/dev after team recast (#423 Usual Suspects → Apollo 13) and model updates. Cross-repo PR (diberry/squad → bradygaster/squad). Initial rebase attempts failed due to git worktree confusion — main worktree was checked out to a different branch, causing git checkout commands to silently switch to wrong branches. - -**Problem:** Git commands (checkout, rebase) kept switching to unrelated branches (squad/agent-on-disk-concept, squad/320-fix-migration-guide-version-local) mid-rebase. Root cause: main worktree at C:\Users\diberry\repos\project-squad\squad was checked out to squad/agent-on-disk-concept. Git was treating checkout commands as worktree operations and switching the main worktree's HEAD, aborting the rebase. - -**Solution:** Created dedicated worktree (.worktrees/pao-rebase) for the rebase operation. This isolated the rebase from main worktree state and prevented branch switching. - -**Conflict Resolution (3 files, 7 commits rebased):** -1. **.squad/agents/_alumni/mcmanus/charter.md** - Merged both rule sets: DOCS-TEST SYNC (from upstream reskill) and EXTERNAL COMMS, HUMANIZER, AUDIT TRAIL (from PR #427). Used PowerShell regex to extract and combine both sides. -2. **.squad/routing.md** - Accepted Apollo 13 team names (EECOM, PAO, FIDO) from upstream via `git checkout --ours` (in rebase context, "ours" = upstream, "theirs" = our branch). PAO external comms infrastructure is team-agnostic. -3. **.squad/agents/keaton/history.md** - Accepted deletion via `git rm` (file moved to _alumni in upstream recast). - -**Rebase Commits:** 7 commits from squad/426-pao-external-comms rebased onto upstream/dev (f87a7a5), covering #423 team reskill, #424 SDK switch, #425/#428 test parity, #429 model updates. - -**Force Push:** `git push origin squad/426-pao-external-comms --force-with-lease` succeeded. PR #427 comment posted via gh CLI. - -**Pattern:** When working with git worktrees, always create a dedicated worktree for complex operations (rebase, cherry-pick) to avoid main worktree state interference. Use `git worktree list` to diagnose unexpected branch switching. -### SDK Init Flow Deep Dive (2026-03-08) -Traced complete `squad init --sdk` flow end-to-end for unified PRD. Key findings: (1) Init flow has two phases: CLI init creates skeleton files, REPL auto-cast creates team members. (2) Critical gap: squad.config.ts is never updated after auto-cast — members exist in .squad/ but not in config. (3) Ralph is inconsistently created (auto-cast yes, CLI init no). (4) No commands exist for adding/removing members post-init. (5) CastingEngine class exists but is never called during init — LLM-based Init Mode prompt is used instead. Roadmap written to .squad/identity/sdk-init-implementation-roadmap.md with 7 fixes prioritized by dependency graph. Critical path: sync utility → Ralph fixes → CastingEngine integration → hire/remove commands. High-risk items: squad.config.ts AST parsing (considered regex alternative). Open questions: AST vs regex for config sync, CastingEngine augment vs replace LLM, Ralph always-on vs opt-in. - -📌 **Team update (2026-03-11T01:25:00Z):** SDK Init decisions finalized: Phase-based quality improvement program, CastingEngine canonical casting, squad.config.ts as source of truth, Ralph always-included, implementation priority order (sync utility first, then Ralph fixes, then CastingEngine integration). All decisions merged to decisions.md. Ready to start Phase 1 implementation. - -### Adoption Tracking Tier 1 Implementation (2026-03-10) -Implemented Flight's privacy-first adoption monitoring strategy on PR #326 branch. Moved `.squad/adoption/` → `.github/adoption/` for better GitHub integration. Stripped tracking.md to aggregate-only metrics (removed all individual repo names/URLs). Updated GitHub Action workflow (adoption-report.yml) and monitoring script (scripts/adoption-monitor.mjs) to write reports to `.github/adoption/reports/`. Removed "Built with Squad" showcase link from README.md (deferred to Tier 2 opt-in feature). This honors the principle: collect aggregate metrics via public APIs, but never publish individual repo lists without explicit consent. Test discipline: verified npm run build passes; docs-build.test.ts passed structure tests (Astro build failure unrelated to changes). Committed with clear message explaining privacy rationale. - -📌 **Team update (2026-03-10T12-55-49Z):** Adoption tracking Tier 1 complete and merged to decisions.md. Privacy-first architecture confirmed: aggregate metrics only, opt-in for individual repos, public showcase only when 5+ projects opt in. Append-only file governance enforced (no deletions in history.md or decisions.md). Microsoft ampersand style guide adopted for documentation. - -### Issue Triage (2026-03-22T06:44:01Z) - -**Flight triaged 6 unlabeled issues and filed 1 new issue.** - -EECOM assigned: -- **#481 (StorageProvider PRD)** → squad:control + squad:eecom (type system abstraction + runtime integration) -- **#479 (history-shadow race condition)** → squad:eecom + squad:retro (production bug; mitigation through StorageProvider atomicity) - -Pattern: Three architectural gaps identified (agent spec, state abstraction, quality tooling) + one production bug. StorageProvider abstraction critical for #479 atomicity fix. - -📌 **Team update (2026-03-22T06:44:01Z):** Flight issued comprehensive triage. EECOM owns StorageProvider PRD spec (#481) + history-shadow race mitigation (#479). Ready to begin implementation on next sprint. - -### PR #483 Review & Merge — Platform Adapter Timeout Fix (2026-03-22) - -Reviewed and merged diberry's fix for platform-adapter test timeouts that were blocking all 8 open PRs. Root cause: `getAvailableWorkItemTypes()` called `execFileSync('az', ...)` with no timeout — in CI where az CLI is installed but no real ADO org exists, it hangs indefinitely until Vitest kills it at 5s. - -**Fix pattern:** `{ ...EXEC_OPTS, timeout: 3_000 }` — spread existing exec options and add a 3-second timeout. The existing catch block already returns sensible default work item types, so timeout errors fall through gracefully. This is the correct pattern for any external CLI call that might hang: add a timeout to execFileSync and ensure the catch block has a fallback. - -**Rebase note:** Branch was already clean on top of dev (1 commit ahead, no divergence). No rebase was needed. - -📌 **Team update:** PR #483 merged (squash). This unblocks CI for all open PRs that were failing on platform-adapter test timeouts. The remaining CI failure across PRs is the broken docs link (separate issue). - -### PR #480 Review & Merge — History Race Condition Fix (2026-03-22) - -Reviewed and merged PR #480 (async mutex + atomic writes + 14 tests). Addresses race condition in history-shadow file operations under concurrent load. +- **Fix:** Replaced all hardcoded "Brady" in template examples with generic `{user}` / `{name}` placeholders. Canonical sources: `.squad-templates/squad.agent.md` and `.copilot/skills/init-mode/SKILL.md`. Template sync (`node scripts/sync-templates.mjs`) propagated squad.agent.md to `.github/agents/` but did NOT sync init-mode SKILL.md to package templates — those required manual edits in both `packages/squad-cli/templates/skills/init-mode/SKILL.md` and `packages/squad-sdk/templates/skills/init-mode/SKILL.md`. +- **Context:** PR #942 from tamirdresher's fork was retargeted from `insider` to `dev`, causing 29 files in the diff when only 3 commits (4 files relevant to dev) were the actual fix. Cherry-picked the 3 fix commits onto a clean `squad/942-rebase-type-safety` branch from dev, resolving conflicts where insider-only files (skill.ts, cross-package-exports.test.ts) didn't exist on dev. Dropped the `escapeYamlValue` import and APM YAML generation function from init.ts since skill.ts doesn't exist on dev. Opened #963 as the clean replacement, closed #942. +- **Key lesson:** When cherry-picking from an insider-based branch to dev, expect modify/delete conflicts for files that only exist on insider. Always verify the base assumptions of each change — imports referencing insider-only modules must be dropped or adapted. +- **Context:** Three Copilot review comments on PR #767: (1) `teamRoot` was set to `workTreeRoot` but `.squad/` may live in the main checkout when running inside a git worktree — should derive from `detectSquadDir().path`, (2) `generateLoopFile()` hardcoded the full loop.md scaffold inline, duplicating `templates/loop.md`, (3) docs said `gh` was optional but code hard-requires `gh copilot` unless `--agent-cmd` is passed. +- **Context:** Copilot code review on PR #767 flagged three issues in the loop command: (1) `execFile` buffered stdout/stderr but never printed it — users saw no Copilot output during loop rounds, (2) `loop.md` was resolved relative to `dest` but execution used `teamRoot` (derived from `.squad/` parent), creating a CWD mismatch in worktree scenarios, (3) docs said `description` defaults to `""` but code uses `'Squad Loop'`. +- **Context:** `archiveDecisions()` in `packages/squad-cli/src/cli/core/nap.ts` silently returned `null` when all `###` entries were <30 days old (`old.length === 0`), even if the file was well over 20KB. Active projects generating many decisions per session could hit 145KB+ — 35K tokens burned per agent spawn. +- **Fix:** Added a count-based fallback after the age-based split. When `old.length === 0` and total file size exceeds `DECISION_THRESHOLD` (20KB), the fallback separates recent entries into dated vs undated, sorts dated by age (most recent first), keeps entries that fit under the threshold budget, and archives the rest. Undated entries are always preserved — they are foundational directives per Procedures' guidance. +- ### CLI Version Subcommand Pattern (2026-03-23 Release Incident) +- 📌 **Team update (2026-03-22T09-35Z — Wave 1):** Economy mode fully implemented: ECONOMY_MODEL_MAP + resolveModel() integration in SDK, `squad economy on|off` CLI command, `--economy` flag, 34 tests passing. PR #504 open for review. Soft dependency: #464 rate limit UX should offer economy mode as recovery. Next: Phase 1 of ambient personal squad (T1–T5, T19) — ready to start immediately after merging current work. Procedures wrote governance proposals for squad.agent.md — awaiting Flight review. +- **Root cause:** The catch block in `shell/index.ts` line ~1119 always emitted `genericGuidance()` unless `SQUAD_DEBUG=1`. Rate limit errors never got special treatment despite `RateLimitError` existing in `adapter/errors.ts`. +- `npm pack` produces a complete, installable tarball (~275KB packed, 1.2MB unpacked). Package includes dist/, templates/, scripts/, README.md per package.json "files" field. Postinstall script (patch-esm-imports.mjs) patches @github/copilot-sdk for Node 24+ compatibility. Tarball can be installed locally (`npm install ./tarball.tgz`) and commands execute via `node node_modules/@bradygaster/squad-cli/dist/cli-entry.js`. Both squad-cli and squad-sdk must be installed together — cli depends on sdk with "*" version specifier. All 27+ CLI commands are lazy-loaded at runtime; `--help` validates command routing without executing full logic. +- **Context:** Two cross-platform bugs broke Squad on Windows: (1) log filenames contained colons in ISO 8601 timestamps (illegal on Windows), (2) `.squad/config.json` contained absolute machine-specific `teamRoot` path. +- 3. Updated live `.squad/config.json` in repo to remove machine-specific path +- **Test Impact:** All 150 tests pass. Communication adapter test doesn't validate specific filename format (structural test, not behavioral). +- **Context:** CastingEngine class (Issue #138, M3-2) existed in SDK with curated universe templates (The Usual Suspects, Ocean's Eleven) but was completely bypassed during `squad init`. LLM picked arbitrary names, and charter generation used regex-based `personalityForRole()` instead of template backstories. + +## Recent preserved tail **Fix pattern:** Race conditions in history operations require three-layer defense: (1) async mutex for write serialization, (2) atomic file operations (write-then-rename), (3) comprehensive test coverage (14 tests for edge cases). This pattern applies to any persistent state under concurrent access. @@ -362,5 +115,5 @@ Executed 3 tasks across 2 waves: economy mode (#500, PR #504), node:sqlite fix ( 5. `resolution.test.ts` - Added 3 tests. **Pattern:** `resolveGlobalSquadPath()` returns the container; `ensurePersonalSquadDir()` creates the subdirectory the rest of the system looks for. -📌 **Team update (2026-03-25T18:11Z):** Fixed #590 personal squad path regression — getPersonalSquadRoot() now uses canonical personal-squad/ subdirectory like esolvePersonalSquadDir() and nsurePersonalSquadDir(). Committed on squad/590-fix-personal-squad-root. FIDO found same bug in shell/index.ts → work passed to CONTROL for full sweep revision. Awaiting FIDO re-review. - +📌 **Team update (2026-03-25T18:11Z):** Fixed #590 personal squad path regression — getPersonalSquadRoot() now uses canonical personal-squad/ subdirectory like +esolvePersonalSquadDir() and nsurePersonalSquadDir(). Committed on squad/590-fix-personal-squad-root. FIDO found same bug in shell/index.ts → work passed to CONTROL for full sweep revision. Awaiting FIDO re-review. diff --git a/.squad/agents/fido/history.md b/.squad/agents/fido/history.md index 9c88ff7c0..6d19fd781 100644 --- a/.squad/agents/fido/history.md +++ b/.squad/agents/fido/history.md @@ -1,218 +1,25 @@ -# FIDO +# Fido history -> Flight Dynamics Officer +Summarized by Scribe on 2026-08-19T13:11:34.130-07:00 because this history exceeded 15KB. +Full pre-summary history archived at `.squad/agents/fido/history-archive-2026-08-19T13-11-34.130-07-00.md`. -## Core Context +## Condensed signals -Quality gate authority for all PRs. Test assertion arrays (EXPECTED_GUIDES, EXPECTED_FEATURES, EXPECTED_SCENARIOS, etc.) MUST stay in sync with files on disk. When reviewing PRs with CI failures, always check if dev branch has the same failures — don't block PRs for pre-existing issues. 3,931 tests passing, 149 test files, ~89s runtime. +- Quality gate authority for all PRs. Test assertion arrays (EXPECTED_GUIDES, EXPECTED_FEATURES, EXPECTED_SCENARIOS, etc.) MUST stay in sync with files on disk. When reviewing PRs with CI failures, always check if dev branch has the same failures — don't block PRs for pre-existing issues. 3,931 tests passing, 149 test files, ~89s runtime. +- 📌 **Team update (2026-03-26T06:41:00Z — Crash Recovery Execution & Community PR Review):** Post-CLI crash recovery completed: Round 1 baseline verified (5,038 tests ✅ green), Round 2 executed duplicate closures (#605/#604/#602) and 9-PR community batch review. FIDO approved 3 PRs (#625 notification-routing, #603 Challenger agent, #608 security policy—merged via Coordinator) and issued change requests on 6 PRs identifying systemic issues: changeset package naming (4 PRs used unscoped `squad-cli` instead of `@bradygaster/squad-cli`); file paths (2 PRs placed files at root instead of correct package structure). Quality gate result: high-bar community acceptance—approved 3/9 (33%), change-request 6/9 (67%), 0 rejections. PR #592 (legacy, high-quality) also merged. All actions complete; dev branch remains green. +- 📌 **Team update (2026-03-25T15:23Z — Triage Session & PR Review Batch):** FIDO reviewed 10 open PRs for quality and merge readiness. Identified 3 duplicate/overlap pairs consolidating 6 PRs into 4: #607 (retro enforcement, comprehensive) approved for merge, #605 closed as duplicate. #603 (Challenger agent, correct paths) approved, #604 closed as duplicate. #606 (tiered memory superset) approved, #602 closed as duplicate. Merge-ready: #611 (blocked on #610), #592 (joniba wiring guide, high-quality). Decisions merged. +- ### Test Assertion Sync Discipline +- EXPECTED_* arrays in docs-build.test.ts must match filesystem reality. When PRs add new content files, verify the corresponding test arrays are updated. Consider dynamic discovery pattern (used for blog posts) for resilience against content additions. Stale assertions that block CI are FIDO's responsibility. **Fixed PR #331:** EXPECTED_SCENARIOS expanded to 25 entries, EXPECTED_FEATURES array created with 32 entries (commit 6599db6). +- 📌 **Team update (2026-03-26T06:41:00Z — Crash Recovery Execution & Community PR Review):** Post-CLI crash recovery completed: Round 1 baseline verified (5,038 tests ✅ green), Round 2 executed duplicate closures (#605/#604/#602) and 9-PR community batch review. FIDO approved 3 PRs (#625 notification-routing, #603 Challenger agent, #608 security policy—merged via Coordinator) and issued change requests on 6 PRs identifying systemic issues: changeset package naming (4 PRs used unscoped `squad-cli` instead of `@bradygaster/squad-cli`); file paths (2 PRs placed files at root instead of correct package structure). Quality gate result: high-bar community acceptance—approved 3/9 (33%), change-request 6/9 (67%), 0 rejections. PR #592 (legacy, high-quality) also merged. All actions complete; dev branch remains green. Decision inbox merged and deleted. Next: Monitor 6 change-request PRs for author responses. +- 📌 **Team update (2026-03-25T15:23Z — Triage Session & PR Review Batch):** FIDO reviewed 10 open PRs for quality and merge readiness. Identified 3 duplicate/overlap pairs consolidating 6 PRs into 4: #607 (retro enforcement, comprehensive) approved for merge, #605 closed as duplicate (less comprehensive). #603 (Challenger agent, correct paths) approved for merge, #604 closed as duplicate (wrong file paths). #606 (tiered memory superset, 3-tier model) approved for merge, #602 closed as duplicate (narrower 2-tier scope). Merge-ready PRs identified: #611 (blocked on #610), #592 (joniba wiring guide, high-quality). Draft #567 not ready. Impact: reduces PR count from 10 to 7, eliminates file conflicts, preserves unique value. All other PRs (#611, #608, #592, #567) can proceed independently. Decisions merged to decisions.md and decisions inbox deleted. +- EXPECTED_* arrays in docs-build.test.ts must match filesystem reality. When PRs add new content files, verify the corresponding test arrays are updated. Consider dynamic discovery pattern (used for blog posts) for resilience against content additions. Stale assertions that block CI are FIDO's responsibility. +- Verdict scale: GO (merge), FAIL (block until fixed), NO-GO (reject). Always verify: test discipline (assertions synced), CI status (distinguish pre-existing vs new failures), content accuracy, cross-reference validity. When detecting CI failures, run baseline comparison (dev branch vs PR branch) to isolate regressions. +- Tests reading live .squad/ files must assert structure/behavior, not specific agent names. Names change during team rebirths. Two test classes: live-file tests (survive rebirths, property checks) and inline-fixture tests (self-contained, can hardcode). +- cli-command-wiring.test.ts prevents "unwired command" bug: verifies every .ts file in commands/ is imported in cli-entry.ts. Bidirectional validation. +- `test/init-scaffolding.test.ts` — 15 tests: casting directory scaffolding (verifies .squad/casting/ + all 3 JSON files), no-remote resilience (init succeeds without git remote), doctor validation after init (zero failures). Follows existing test conventions — vitest, randomBytes temp dirs in cwd, compiled dist imports. -📌 **Team update (2026-03-26T06:41:00Z — Crash Recovery Execution & Community PR Review):** Post-CLI crash recovery completed: Round 1 baseline verified (5,038 tests ✅ green), Round 2 executed duplicate closures (#605/#604/#602) and 9-PR community batch review. FIDO approved 3 PRs (#625 notification-routing, #603 Challenger agent, #608 security policy—merged via Coordinator) and issued change requests on 6 PRs identifying systemic issues: changeset package naming (4 PRs used unscoped `squad-cli` instead of `@bradygaster/squad-cli`); file paths (2 PRs placed files at root instead of correct package structure). Quality gate result: high-bar community acceptance—approved 3/9 (33%), change-request 6/9 (67%), 0 rejections. PR #592 (legacy, high-quality) also merged. All actions complete; dev branch remains green. +## Recent preserved tail -📌 **Team update (2026-03-25T15:23Z — Triage Session & PR Review Batch):** FIDO reviewed 10 open PRs for quality and merge readiness. Identified 3 duplicate/overlap pairs consolidating 6 PRs into 4: #607 (retro enforcement, comprehensive) approved for merge, #605 closed as duplicate. #603 (Challenger agent, correct paths) approved, #604 closed as duplicate. #606 (tiered memory superset) approved, #602 closed as duplicate. Merge-ready: #611 (blocked on #610), #592 (joniba wiring guide, high-quality). Decisions merged. - -## Key Learnings - -### Test Assertion Sync Discipline -EXPECTED_* arrays in docs-build.test.ts must match filesystem reality. When PRs add new content files, verify the corresponding test arrays are updated. Consider dynamic discovery pattern (used for blog posts) for resilience against content additions. Stale assertions that block CI are FIDO's responsibility. **Fixed PR #331:** EXPECTED_SCENARIOS expanded to 25 entries, EXPECTED_FEATURES array created with 32 entries (commit 6599db6). -📌 **Team update (2026-03-26T06:41:00Z — Crash Recovery Execution & Community PR Review):** Post-CLI crash recovery completed: Round 1 baseline verified (5,038 tests ✅ green), Round 2 executed duplicate closures (#605/#604/#602) and 9-PR community batch review. FIDO approved 3 PRs (#625 notification-routing, #603 Challenger agent, #608 security policy—merged via Coordinator) and issued change requests on 6 PRs identifying systemic issues: changeset package naming (4 PRs used unscoped `squad-cli` instead of `@bradygaster/squad-cli`); file paths (2 PRs placed files at root instead of correct package structure). Quality gate result: high-bar community acceptance—approved 3/9 (33%), change-request 6/9 (67%), 0 rejections. PR #592 (legacy, high-quality) also merged. All actions complete; dev branch remains green. Decision inbox merged and deleted. Next: Monitor 6 change-request PRs for author responses. - -📌 **Team update (2026-03-25T15:23Z — Triage Session & PR Review Batch):** FIDO reviewed 10 open PRs for quality and merge readiness. Identified 3 duplicate/overlap pairs consolidating 6 PRs into 4: #607 (retro enforcement, comprehensive) approved for merge, #605 closed as duplicate (less comprehensive). #603 (Challenger agent, correct paths) approved for merge, #604 closed as duplicate (wrong file paths). #606 (tiered memory superset, 3-tier model) approved for merge, #602 closed as duplicate (narrower 2-tier scope). Merge-ready PRs identified: #611 (blocked on #610), #592 (joniba wiring guide, high-quality). Draft #567 not ready. Impact: reduces PR count from 10 to 7, eliminates file conflicts, preserves unique value. All other PRs (#611, #608, #592, #567) can proceed independently. Decisions merged to decisions.md and decisions inbox deleted. - -## Learnings - -### Test Assertion Sync Discipline -EXPECTED_* arrays in docs-build.test.ts must match filesystem reality. When PRs add new content files, verify the corresponding test arrays are updated. Consider dynamic discovery pattern (used for blog posts) for resilience against content additions. Stale assertions that block CI are FIDO's responsibility. - -### PR Quality Gate Pattern -Verdict scale: GO (merge), FAIL (block until fixed), NO-GO (reject). Always verify: test discipline (assertions synced), CI status (distinguish pre-existing vs new failures), content accuracy, cross-reference validity. When detecting CI failures, run baseline comparison (dev branch vs PR branch) to isolate regressions. - -### Name-Agnostic Testing -Tests reading live .squad/ files must assert structure/behavior, not specific agent names. Names change during team rebirths. Two test classes: live-file tests (survive rebirths, property checks) and inline-fixture tests (self-contained, can hardcode). - -### Dynamic Content Discovery -Blog tests use filesystem discovery (readdirSync) instead of hardcoded arrays. Pattern: discover from disk, sort, validate build output exists. - -### Command Wiring Regression Test -cli-command-wiring.test.ts prevents "unwired command" bug: verifies every .ts file in commands/ is imported in cli-entry.ts. Bidirectional validation. - -### CLI Packaging Smoke Test -cli-packaging-smoke.test.ts validates packaged CLI artifact (npm pack → install → execute). Tests 27 commands + 3 aliases. Catches: missing imports, broken exports, bin misconfiguration, ESM resolution failures. Windows cleanup requires retry logic (EBUSY errors) — use rmSync with maxRetries + retryDelay, wrap in try/catch. - -### Agent Name Extraction Test Coverage (#577) -Extracted inline regex-based agent name parsing from `shell/index.ts` into testable pure function `parseAgentFromDescription` in `shell/agent-name-parser.ts`. 30 tests across 7 categories. 3-tier matching: (1) leading emoji+name+colon regex, (2) name+colon anywhere, (3) fuzzy word-boundary match. Shell index.ts delegates to this function. - -### Init Scaffolding Completeness Tests (#579) -`test/init-scaffolding.test.ts` — 15 tests: casting directory scaffolding (verifies .squad/casting/ + all 3 JSON files), no-remote resilience (init succeeds without git remote), doctor validation after init (zero failures). Follows existing test conventions — vitest, randomBytes temp dirs in cwd, compiled dist imports. - -### Personal Squad Init Discovery Tests (#576) -`test/personal-squad-init.test.ts` — 35 tests, 10 describe blocks. Key finding: `resolvePersonalSquadDir()` is install-method-agnostic — resolves from env vars and `os.homedir()`, never from `process.argv`. npx issue #576 is NOT in path resolution but in CLI command wiring or `--global` flag routing. SDK layer works correctly. - -### Publish Policy CI Gate (#557) -Added `publish-policy` job to squad-ci.yml: scans `.github/workflows/*.yml` for bare `npm publish` commands missing `-w`/`--workspace`. `test/publish-policy.test.ts` (36 tests). Meta-references (echo, grep, YAML name keys) must be excluded from lint. - -### PR Review Batch — Community PRs -Community contributors consistently struggle with: (a) scoped npm package names in changesets (use `@bradygaster/squad-cli` not `squad-cli`), (b) monorepo file placement (skills in `packages/squad-cli/templates/skills/`). Both preventable with better contributor docs. Changeset package name mismatch is most common error (4/9 Tamir PRs). - -📌 **Team update (2026-07-29T17:11:56+10:00 — Issue #1556 / PR #1557):** A new required CI check `squad-workflow-lint` now exists in `.github/workflows/squad-workflow-lint.yml`. It runs actionlint 1.7.12 + shellcheck 0.10.0 against all 5 workflow/template directories, including the canonical `.squad-templates/workflows/` sources. FIDO should treat this as a required gate alongside existing CI checks — PRs that introduce SC2086, unquoted variables, or invalid action syntax in workflow files will fail this check. All known SC2086 findings across Squad's own workflows were fixed in PR #1557. -cli-packaging-smoke.test.ts validates packaged CLI artifact (npm pack → install → execute). Tests 27 commands + 3 aliases. Catches: missing imports, broken exports, bin misconfiguration, ESM resolution failures. Complements source-level wiring test. - -### CastingEngine Integration Review -CastingEngine augments LLM casting with curated names for recognized universes. Unrecognized universes preserve LLM names. Import from `@bradygaster/squad-sdk/casting`, use casting-engine.ts AgentRole type (9 roles). Partial mapping: unmapped roles skip engine casting. - -### PR #331 Quality Gate Review — NO-GO (Blocking Issues Found) (2026-03-10T14:13:00Z) - -**CRITICAL VIOLATIONS DETECTED:** - -1. **Stale Test Assertions (Hard Rule Violation)** — EXPECTED_SCENARIOS array in test/docs-build.test.ts contains only 7 values ['issue-driven-dev', 'existing-repo', 'ci-cd-integration', 'solo-dev', 'monorepo', 'team-of-humans', 'cross-org-auth'], but 25 scenario files exist on disk (aspire-dashboard, client-compatibility, disaster-recovery, keep-my-squad, large-codebase, mid-project, multi-codespace, multiple-squads, new-project, open-source, private-repos, release-process, scaling-workstreams, switching-models, team-portability, team-state-storage, troubleshooting, upgrading, + 7 in array). My charter: "When I add test count assertions, I MUST keep them in sync with the actual files on disk. Stale assertions that block CI are MY responsibility to prevent." This is MY responsibility to catch. - -2. **Missing EXPECTED_FEATURES Array** — PR adds 'features' to the sections list in test/docs-build.test.ts (line 46), but NO EXPECTED_FEATURES array exists. Test line 171 "all expected doc pages produce HTML in dist/" will skip features entirely. 32 feature files exist (.md files in docs/src/content/docs/features/). - -📌 **Team update (2026-03-11T01:27:57Z):** PR #331 quality gate resolved. FIDO fixed test assertion sync in docs-build.test.ts: EXPECTED_SCENARIOS updated to 25 entries, EXPECTED_FEATURES array created with 32 entries, test assertions updated for features validation. Tests: 6/6 passing. Commit: 6599db6. Blocking NO-GO converted to approval gate cleared. Lesson reinforced: test assertions must be synced to filesystem state; CI passing ≠ coverage. - -3. **Incomplete Test Coverage Sync** — PAO's history (line 41) states "Updated EXPECTED_SCENARIOS in docs-build.test.ts to match remaining files" after deleting ralph-operations.md and proactive-communication.md. But the diff shows ONLY a single-line change (adding 'features' to sections array). The full test update was not committed. - -**POSITIVE FINDINGS:** -- ✅ CI passed (test run completed successfully on GitHub) -- ✅ Markdown structure tests pass (6/6 syntax checks) -- ✅ Docs are well-written: sentence-case headings, active voice, present tense, second person -- ✅ Cross-references valid (labels.md link verified) -- ✅ No duplicate "How It Works" heading in reviewer-protocol.md -- ✅ Content intact (no accidental loss) -- ✅ Microsoft Style Guide compliance confirmed - -**ROOT CAUSE:** PAO staged the boundary review changes but the test update commit was incomplete. The assertion arrays must be synchronized before merge. - -**REQUIRED FIX:** Update test/docs-build.test.ts: -1. EXPECTED_SCENARIOS = [ all 25 actual scenario files, sorted ] -2. EXPECTED_FEATURES = [ all 32 actual feature files, sorted ] -3. Regenerate to match disk reality (use filesystem discovery if the project wants test-resilience) - -**VERDICT:** 🔴 **NO-GO** — Merge blocked until test assertions sync with disk state. This is a quality gate violation. - -### Test Assertion Sync Fix (2026-03-10T14:20:00Z) - -**Issue resolved:** Fixed stale test assertions in test/docs-build.test.ts identified during PR #331 review. - -**Changes made:** -1. Expanded EXPECTED_SCENARIOS from 7 to 25 entries (matched all .md files in docs/src/content/docs/scenarios/) -2. Added EXPECTED_FEATURES array with 32 entries (matched all .md files in docs/src/content/docs/features/) -3. Updated test logic to include features section in HTML build validation - -**Validation:** All structure validation tests passing (6/6). Build tests skipped as expected (Astro not installed). Arrays now accurately reflect disk state. - -**Commit:** 6599db6 on branch squad/289-squad-dir-explainer - -**Learning:** When test assertions reference file counts, they MUST be kept in sync with disk reality. The principle applies to ALL assertion arrays (EXPECTED_SCENARIOS, EXPECTED_FEATURES, EXPECTED_GUIDES, EXPECTED_REFERENCE, etc.). Consider dynamic discovery pattern (used in EXPECTED_BLOG) for resilience against content additions. - -📌 **Team update (2026-03-10T14-44-23Z):** PR #310 scroll flicker fix merged. 4 root causes identified: Ink clearTerminal issue, timer amplification, log-update trailing newline, unstable Static keys. Postinstall patch pattern adopted for Ink internals. Version pin recommended for stability gate. Build: 3,931 tests pass, zero regressions. -### PR #331 Quality Gate Review — NO-GO (Blocking Issues Found) (2026-03-10T14:13:00Z) - -**CRITICAL VIOLATIONS DETECTED:** - -1. **Stale Test Assertions (Hard Rule Violation)** — EXPECTED_SCENARIOS array in test/docs-build.test.ts contains only 7 values ['issue-driven-dev', 'existing-repo', 'ci-cd-integration', 'solo-dev', 'monorepo', 'team-of-humans', 'cross-org-auth'], but 25 scenario files exist on disk (aspire-dashboard, client-compatibility, disaster-recovery, keep-my-squad, large-codebase, mid-project, multi-codespace, multiple-squads, new-project, open-source, private-repos, release-process, scaling-workstreams, switching-models, team-portability, team-state-storage, troubleshooting, upgrading, + 7 in array). My charter: "When I add test count assertions, I MUST keep them in sync with the actual files on disk. Stale assertions that block CI are MY responsibility to prevent." This is MY responsibility to catch. - -2. **Missing EXPECTED_FEATURES Array** — PR adds 'features' to the sections list in test/docs-build.test.ts (line 46), but NO EXPECTED_FEATURES array exists. Test line 171 "all expected doc pages produce HTML in dist/" will skip features entirely. 32 feature files exist (.md files in docs/src/content/docs/features/). - -📌 **Team update (2026-03-11T01:27:57Z):** PR #331 quality gate resolved. FIDO fixed test assertion sync in docs-build.test.ts: EXPECTED_SCENARIOS updated to 25 entries, EXPECTED_FEATURES array created with 32 entries, test assertions updated for features validation. Tests: 6/6 passing. Commit: 6599db6. Blocking NO-GO converted to approval gate cleared. Lesson reinforced: test assertions must be synced to filesystem state; CI passing ≠ coverage. - -3. **Incomplete Test Coverage Sync** — PAO's history (line 41) states "Updated EXPECTED_SCENARIOS in docs-build.test.ts to match remaining files" after deleting ralph-operations.md and proactive-communication.md. But the diff shows ONLY a single-line change (adding 'features' to sections array). The full test update was not committed. - -**POSITIVE FINDINGS:** -- ✅ CI passed (test run completed successfully on GitHub) -- ✅ Markdown structure tests pass (6/6 syntax checks) -- ✅ Docs are well-written: sentence-case headings, active voice, present tense, second person -- ✅ Cross-references valid (labels.md link verified) -- ✅ No duplicate "How It Works" heading in reviewer-protocol.md -- ✅ Content intact (no accidental loss) -- ✅ Microsoft Style Guide compliance confirmed - -**ROOT CAUSE:** PAO staged the boundary review changes but the test update commit was incomplete. The assertion arrays must be synchronized before merge. - -**REQUIRED FIX:** Update test/docs-build.test.ts: -1. EXPECTED_SCENARIOS = [ all 25 actual scenario files, sorted ] -2. EXPECTED_FEATURES = [ all 32 actual feature files, sorted ] -3. Regenerate to match disk reality (use filesystem discovery if the project wants test-resilience) - -**VERDICT:** 🔴 **NO-GO** — Merge blocked until test assertions sync with disk state. This is a quality gate violation. - -### Test Assertion Sync Fix (2026-03-10T14:20:00Z) - -**Issue resolved:** Fixed stale test assertions in test/docs-build.test.ts identified during PR #331 review. - -**Changes made:** -1. Expanded EXPECTED_SCENARIOS from 7 to 25 entries (matched all .md files in docs/src/content/docs/scenarios/) -2. Added EXPECTED_FEATURES array with 32 entries (matched all .md files in docs/src/content/docs/features/) -3. Updated test logic to include features section in HTML build validation - -**Validation:** All structure validation tests passing (6/6). Build tests skipped as expected (Astro not installed). Arrays now accurately reflect disk state. - -**Commit:** 6599db6 on branch squad/289-squad-dir-explainer - -**Learning:** When test assertions reference file counts, they MUST be kept in sync with disk reality. The principle applies to ALL assertion arrays (EXPECTED_SCENARIOS, EXPECTED_FEATURES, EXPECTED_GUIDES, EXPECTED_REFERENCE, etc.). Consider dynamic discovery pattern (used in EXPECTED_BLOG) for resilience against content additions. - -### Issue Triage (2026-03-22T06:44:01Z) - -**Flight triaged 6 unlabeled issues and filed 1 new issue.** - -FIDO assigned: -- **#477 (Code Quality Linting PRD)** → squad:fido (monorepo async/promise quality, ESLint 9 PoC ready) - -Pattern: Quality tooling gap identified. ESLint 9 modernization + async/promise pattern enforcement for monorepo. - -📌 **Team update (2026-03-22T06:44:01Z):** Flight issued comprehensive triage. FIDO owns Code Quality Linting PRD (#477). ESLint 9 PoC already drafted; ready for implementation planning. - -### Agent Name Extraction Test Coverage (#577) - -Extracted inline regex-based agent name parsing from `shell/index.ts` into a testable pure function `parseAgentFromDescription` in `shell/agent-name-parser.ts`. Created 30 tests across 7 categories: happy path, emoji variations, case insensitivity, fuzzy fallback, no-match, edge cases, and adversarial inputs. The function uses a 3-tier matching strategy: (1) leading emoji+name+colon regex, (2) name+colon anywhere regex, (3) fuzzy word-boundary match against known agent names. Shell index.ts now imports and delegates to this function. Build and tests green. - -**Learning:** Inline regex logic in UI code is untestable and fragile. Extracting to a pure function with explicit inputs (description string + known names array) makes it trivially testable and enables VOX's parallel fix to land cleanly. - -📌 **Team update (2026-03-23T23:15Z):** Orchestration complete. Agent name extraction refactor shipped: FIDO's parser module (30 tests, all passing), VOX's 3-tier cascading patterns, Procedures' spawn template standardization. All decisions merged to decisions.md. Agent IDs now display correctly in Copilot CLI. Canonical patterns: `agent-name-parser.ts` is source of truth for extraction logic. -### Init Scaffolding Completeness Tests (#579) - -Added `test/init-scaffolding.test.ts` — 15 tests covering three gaps exposed by issue #579: - -1. **Casting directory scaffolding** — After `initSquad()` and `runInit()`, verifies `.squad/casting/` directory and all three JSON files (registry.json, policy.json, history.json) exist and parse as valid JSON. Also confirms re-init does not overwrite existing casting files. - -2. **No-remote resilience** — Confirms init succeeds without errors when: git repo has no remote configured, brand-new `git init` repo, or no git at all. Uses `execFileSync` to create isolated git repos in temp dirs. - -3. **Doctor validation after init** — Runs `runDoctor()` against a freshly-initialized directory and asserts zero failures, specifically that `casting/registry.json exists` check passes. Also tests negative cases (missing file → fail, corrupt JSON → fail). - -Pattern: Tests follow existing `test/cli/init.test.ts` and `test/cli/doctor.test.ts` conventions — vitest, `randomBytes` temp dirs in cwd, imports from compiled dist via package exports (`@bradygaster/squad-cli/core/init`, `@bradygaster/squad-cli/commands/doctor`, `@bradygaster/squad-sdk`). - -Commit: 7660a27 on branch squad/579-init-scaffolding-hardening. - -### Personal Squad Init Discovery Tests (#576) - -**Task:** Write tests for personal squad discovery and init flows (Issue #576 — npx init --global not discovering personal squad). - -**Test file:** `test/personal-squad-init.test.ts` — 35 tests, 10 describe blocks, all passing. - -**Coverage areas:** -1. `resolveGlobalSquadPath()` — platform-specific path resolution (Windows APPDATA, Linux XDG_CONFIG_HOME, consistency) -2. `resolvePersonalSquadDir()` — kill-switch (SQUAD_NO_PERSONAL), directory existence, npx-agnostic discovery -3. `personalInit` contract — directory structure creation, config.json shape, idempotency -4. `resolveSquadPaths()` — personalDir field inclusion, null when disabled -5. Edge: empty personal-squad dir (exists but no agents/) -6. Edge: partial state (agent dirs without charter.md, missing Role metadata defaults to "personal", stray files skipped) -7. `mergeSessionCast()` — project-wins precedence, case-insensitive collision, empty inputs -8. `ensureSquadPathTriple()` — personal dir in allowed roots, null personalDir graceful handling -9. Charter metadata parsing edge cases (whitespace trimming, sourceDir correctness, multi-agent discovery) - -**Key finding:** `resolvePersonalSquadDir()` is install-method-agnostic — it resolves from env vars and `os.homedir()`, never from `process.argv`. The npx issue (#576) is therefore NOT in path resolution but likely in the CLI command wiring or the `--global` flag routing. Tests confirm the SDK layer works correctly. - -**Commit:** c307187 on branch squad/576-personal-squad-init-npx -### Publish Policy CI Gate (#557) - -Added `publish-policy` job to squad-ci.yml — lightweight lint that scans all `.github/workflows/*.yml` for bare `npm publish` commands missing `-w`/`--workspace`. Catches the incident class where root package.json gets published instead of a workspace package. Also wrote `test/publish-policy.test.ts` (36 tests) covering: workspace-scoped passes, bare publish fails, comment/echo/grep/YAML-name line skipping, findViolations line numbering, and live validation of all 15 workflow files. Key pattern: meta-references (echo, grep, YAML name keys containing "npm publish") must be excluded from lint — the CI script's own text would otherwise self-trigger. - -📌 **Team update (2026-03-24T06-release-hardening):** Publish policy CI gate (#557) implemented. Added `publish-policy` job to squad-ci.yml: lightweight lint scans `.github/workflows/*.yml` for bare `npm publish` commands, rejects non-workspace-scoped invocations. Wrote test/publish-policy.test.ts (36 tests) validating: workspace-scoped passes, bare publish fails, meta-reference (echo/grep/YAML-name) skipping, live validation of 15 workflow files. Pattern: catch "publish root package.json" incident class before merge. Both lint + playbook docs create enforcement + education loop. - -### PR Review Batch — 10 Open PRs (2026-03-24) - -Reviewed all 10 open PRs for quality, test coverage, and merge readiness. - -**Critical finding — Duplicate/overlapping PRs (tamirdresher):** - **PRs #607 / #605** overlap on retrospective ceremony — both add weekly retro ceremony with Ralph enforcement. #607 adds ceremony + enforcement skill + guide (444 lines), #605 modifies existing templates/ceremonies.md + ralph-reference.md (217 lines). Both solve the same problem (retro enforcement) with different file structures. #607 is more comprehensive (includes enforcement guide + pseudocode), #605 is more concise (inline in existing templates). **Verdict: Pick one** — recommend #607 (standalone ceremony file is more discoverable). - **PRs #604 / #603** are complete duplicates — both add Challenger agent template + fact-checking skill. #604 has `templates/challenger.md` (153 lines), #603 has `.squad/templates/agents/challenger.md` + `.squad/skills/fact-checking/SKILL.md` (133 lines). File locations differ but content is nearly identical. **Verdict: Close one as duplicate** — recommend #603 (file locations match project conventions). - **PRs #606 / #602** overlap on tiered memory/history — #606 adds tiered-memory skill (hot/cold/wiki tiers, 370 lines), #602 adds tiered-history skill (hot/cold split, 158 lines). #606 is broader (3 tiers, scribe integration, spawn templates), #602 is narrower (2 tiers, history.md only). Both cite same production data source. **Verdict: #606 supersedes #602** — recommend closing #602 as subset. @@ -248,4 +55,3 @@ Reviewed 9 community PRs (8 from tamirdresher, 1 from eric-vanartsdalen). Key fi 3. **Verdicts:** ✅ MERGE: #625 (notification-routing), #603 (Challenger agent), #608 (SECURITY.md). ⚠️ NEEDS CHANGES: #623, #622, #621, #614 (changeset fix), #607, #606 (path restructuring). **Learning:** Community contributors consistently struggle with two things: (a) scoped npm package names in changesets, and (b) monorepo file placement. Both are preventable with better contributor docs. - diff --git a/.squad/agents/flight/history.md b/.squad/agents/flight/history.md index 03aa6de4d..91a557e26 100644 --- a/.squad/agents/flight/history.md +++ b/.squad/agents/flight/history.md @@ -1,181 +1,24 @@ -# Flight — Project History +# Flight history -> Knowledge accumulated through leading Squad development. +Summarized by Scribe on 2026-08-19T13:11:34.130-07:00 because this history exceeded 15KB. +Full pre-summary history archived at `.squad/agents/flight/history-archive-2026-08-19T13-11-34.130-07-00.md`. ---- - -📌 **Team update (2026-03-26T06:41:00Z — Crash Recovery Execution Complete):** Post-CLI crash recovery executed in 3 rounds. Round 1: Flight audited PR/issue state (found #617 merged, #619 conflicting, 3 dupes #605/#604/#602 open); FIDO verified baseline (5,038 tests ✅ green); Scribe merged stale inbox. Round 2: Flight closed 3 duplicate PRs with rationale; Procedures rebased PR #619 (model catalog) onto dev, resolved 3 merge conflicts, merged; FIDO reviewed 9 community PRs—approved 3 (#625/#603/#608), requested changes on 6 (package naming, file paths). Round 3: Coordinator merged 3 approved PRs. **10 PRs merged total** (6 merge-plan, 3 community, 1 legacy #592). **3 PRs closed** as duplicates. **6 PRs awaiting author revisions**. **Dev branch green** (5,038 tests). All merge-plan sequence complete. - -📌 **Team update (2026-03-25T15:23Z — Triage Session & PR Review):** Flight triaged 14 untriaged GitHub issues, created prioritized work session plan. Identified high-value quick wins (P1): #610 (docs broken link), #590 (getPersonalSquadRoot bug, P0), #591 (hiring wiring docs). Deferred community feature contributions (#601–#595) pending PR review. FIDO reviewed 10 open PRs, identified 3 duplicate/overlap pairs. Work session priority: #610→PAO, #590→EECOM, #592/#611→Flight review, #588→Procedures. Tamir PRs require proposal-first discipline. Merge-ready: #611 (blocked on #610), #592. - -📌 **Team update (2026-03-23T22:00Z — Release Crisis Recovery):** v0.9.0→v0.9.1 incident resolved. Released v0.9.1 stable on npm after 8-hour debugging marathon. Root causes: dependency validation gap (file: refs in packages), GitHub workflow cache race, npm workspace publish automation broken, no pre-publish verification. Created comprehensive retrospective with 5 root causes and 6 action items (A1–A6). Filed 9 GitHub issues (#556–#564). Pre-flight job added to publish pipeline. Surgeon charter hardened. 10 community PRs merged. Release process skill created at `.squad/skills/release-process/SKILL.md`. - -📌 **Team update (2026-03-22T09-35Z — Wave 1):** Ambient personal squad design validated and 19-task implementation plan authored across 4 PRs. EECOM executing Phase 1–2 (SDK + CLI), Procedures executing Phase 3 (governance) concurrently. All design gaps resolved; dependency graph established. -📌 **Team update (2026-03-26T06:41:00Z — Crash Recovery Execution Complete):** Post-CLI crash recovery executed in 3 rounds. Round 1: Flight audited PR/issue state (found #617 merged, #619 conflicting, 3 dupes #605/#604/#602 open); FIDO verified baseline (5,038 tests ✅ green); Scribe merged stale inbox. Round 2: Flight closed 3 duplicate PRs with rationale; Procedures rebased PR #619 (model catalog) onto dev, resolved 3 merge conflicts, merged; FIDO reviewed 9 community PRs—approved 3 (#625/#603/#608), requested changes on 6 (package naming, file paths). Round 3: Coordinator merged 3 approved PRs. **10 PRs merged total** (6 merge-plan, 3 community, 1 legacy #592). **3 PRs closed** as duplicates. **6 PRs awaiting author revisions**. **Dev branch green** (5,038 tests). All merge-plan sequence complete. Draft #567 parked pending requirements. Decision inbox merged to decisions.md and deleted. Next: Monitor change-request PRs for author responses. - -📌 **Team update (2026-03-25T15:23Z — Triage Session & PR Review):** Flight triaged 14 untriaged GitHub issues, created prioritized work session plan. Identified high-value quick wins (P1): #610 (docs broken link, 5-min fix), #590 (getPersonalSquadRoot bug, P0), #591 (hiring wiring docs). Deferred community feature contributions (#601–#595) pending PR review. Categorized maintenance (P2) and questions for community. FIDO reviewed 10 open PRs, identified 3 duplicate/overlap pairs (6 PRs consolidate to 4: merge #607/#603/#606, close #605/#604/#602). Work session priority: #610→PAO, #590→EECOM, #592/#611→Flight review, #588→Procedures. Established PR review strategy: Tamir PRs require proposal-first discipline before review. Merge-ready identified: #611 (blocked on #610), #592 (joniba wiring guide, high-quality). A2A protocol PRs remain shelved. All 14 issues fully categorized with squad assignments. Decision inbox merged to decisions.md. Session complete; team ready for execution. - -📌 **Team update (2026-03-23T22:00Z — Release Crisis Recovery):** v0.9.0→v0.9.1 incident resolved. Released v0.9.1 stable on npm after 8-hour debugging marathon (should have been 10 min). Root causes: dependency validation gap (file: refs in packages), GitHub workflow cache race, npm workspace publish automation broken, coordinator decision-making under pressure, no pre-publish verification. Created comprehensive retrospective with 5 root causes and 6 action items (A1–A6). Filed 9 GitHub issues (#556–#564) documenting release process improvements. Pre-flight job added to publish pipeline (dependency scanning + semver validation). Surgeon charter hardened with release governance rules. 10 community PRs merged (#569, #570, #571, #555, #552, #568, #572, #513, #573, #574). Discussion board fully triaged (15 discussions: 4 closed, 1 consolidated, 2 converted to issue, 8 kept). Dark mode fix deployed to production. Release process skill created at `.squad/skills/release-process/SKILL.md`. 9 GitHub issues filed for release improvements. Team ready for next cycle. - -📌 **Team update (2026-03-22T09-35Z — Wave 1):** Ambient personal squad design validated and 19-task implementation plan authored across 4 PRs (Phase 1 SDK, Phase 2 CLI, Phase 3 governance, Phase 4 tests). MVP = PR #1 + PR #3. EECOM executing Phase 1–2 (SDK + CLI), Procedures executing Phase 3 (governance) concurrently. All design gaps resolved; dependency graph established. Procedures wrote governance proposals for personal squad + economy mode — awaiting your review. Sims to execute Phase 4 after Phase 1+2 merge. Directive captured: bug #502 (node:sqlite, P1) to be picked up after Wave 1. No blocking issues — ready for execution. - -## Core Context - -Three-branch model (main/dev/insiders). Apollo 13 team, 3931 tests. Boundary review heuristic: "Squad Ships It" — if Squad doesn't ship the code, it's IRL content. Proposal-first: meaningful changes need docs/proposals/ before code. Two-error lockout policy: agent locked out after 2 errors in a session. Test name-agnosticism: framework tests must never depend on dev team's agent names. - -## Historical Learnings Summary (condensed) +## Condensed signals +- 📌 **Team update (2026-03-26T06:41:00Z — Crash Recovery Execution Complete):** Post-CLI crash recovery executed in 3 rounds. Round 1: Flight audited PR/issue state (found #617 merged, #619 conflicting, 3 dupes #605/#604/#602 open); FIDO verified baseline (5,038 tests ✅ green); Scribe merged stale inbox. Round 2: Flight closed 3 duplicate PRs with rationale; Procedures rebased PR #619 (model catalog) onto dev, resolved 3 merge conflicts, merged; FIDO reviewed 9 community PRs—approved 3 (#625/#603/#608), requested changes on 6 (package naming, file paths). Round 3: Coordinator merged 3 approved PRs. **10 PRs merged total** (6 merge-plan, 3 community, 1 legacy #592). **3 PRs closed** as duplicates. **6 PRs awaiting author revisions**. **Dev branch green** (5,038 tests). All merge-plan sequence complete. +- 📌 **Team update (2026-03-25T15:23Z — Triage Session & PR Review):** Flight triaged 14 untriaged GitHub issues, created prioritized work session plan. Identified high-value quick wins (P1): #610 (docs broken link), #590 (getPersonalSquadRoot bug, P0), #591 (hiring wiring docs). Deferred community feature contributions (#601–#595) pending PR review. FIDO reviewed 10 open PRs, identified 3 duplicate/overlap pairs. Work session priority: #610→PAO, #590→EECOM, #592/#611→Flight review, #588→Procedures. Tamir PRs require proposal-first discipline. Merge-ready: #611 (blocked on #610), #592. +- 📌 **Team update (2026-03-23T22:00Z — Release Crisis Recovery):** v0.9.0→v0.9.1 incident resolved. Released v0.9.1 stable on npm after 8-hour debugging marathon. Root causes: dependency validation gap (file: refs in packages), GitHub workflow cache race, npm workspace publish automation broken, no pre-publish verification. Created comprehensive retrospective with 5 root causes and 6 action items (A1–A6). Filed 9 GitHub issues (#556–#564). Pre-flight job added to publish pipeline. Surgeon charter hardened. 10 community PRs merged. Release process skill created at `.squad/skills/release-process/SKILL.md`. +- 📌 **Team update (2026-03-26T06:41:00Z — Crash Recovery Execution Complete):** Post-CLI crash recovery executed in 3 rounds. Round 1: Flight audited PR/issue state (found #617 merged, #619 conflicting, 3 dupes #605/#604/#602 open); FIDO verified baseline (5,038 tests ✅ green); Scribe merged stale inbox. Round 2: Flight closed 3 duplicate PRs with rationale; Procedures rebased PR #619 (model catalog) onto dev, resolved 3 merge conflicts, merged; FIDO reviewed 9 community PRs—approved 3 (#625/#603/#608), requested changes on 6 (package naming, file paths). Round 3: Coordinator merged 3 approved PRs. **10 PRs merged total** (6 merge-plan, 3 community, 1 legacy #592). **3 PRs closed** as duplicates. **6 PRs awaiting author revisions**. **Dev branch green** (5,038 tests). All merge-plan sequence complete. Draft #567 parked pending requirements. Decision inbox merged to decisions.md and deleted. Next: Monitor change-request PRs for author responses. +- 📌 **Team update (2026-03-25T15:23Z — Triage Session & PR Review):** Flight triaged 14 untriaged GitHub issues, created prioritized work session plan. Identified high-value quick wins (P1): #610 (docs broken link, 5-min fix), #590 (getPersonalSquadRoot bug, P0), #591 (hiring wiring docs). Deferred community feature contributions (#601–#595) pending PR review. Categorized maintenance (P2) and questions for community. FIDO reviewed 10 open PRs, identified 3 duplicate/overlap pairs (6 PRs consolidate to 4: merge #607/#603/#606, close #605/#604/#602). Work session priority: #610→PAO, #590→EECOM, #592/#611→Flight review, #588→Procedures. Established PR review strategy: Tamir PRs require proposal-first discipline before review. Merge-ready identified: #611 (blocked on #610), #592 (joniba wiring guide, high-quality). A2A protocol PRs remain shelved. All 14 issues fully categorized with squad assignments. Decision inbox merged to decisions.md. Session complete; team ready for execution. +- 📌 **Team update (2026-03-23T22:00Z — Release Crisis Recovery):** v0.9.0→v0.9.1 incident resolved. Released v0.9.1 stable on npm after 8-hour debugging marathon (should have been 10 min). Root causes: dependency validation gap (file: refs in packages), GitHub workflow cache race, npm workspace publish automation broken, coordinator decision-making under pressure, no pre-publish verification. Created comprehensive retrospective with 5 root causes and 6 action items (A1–A6). Filed 9 GitHub issues (#556–#564) documenting release process improvements. Pre-flight job added to publish pipeline (dependency scanning + semver validation). Surgeon charter hardened with release governance rules. 10 community PRs merged (#569, #570, #571, #555, #552, #568, #572, #513, #573, #574). Discussion board fully triaged (15 discussions: 4 closed, 1 consolidated, 2 converted to issue, 8 kept). Dark mode fix deployed to production. Release process skill created at `.squad/skills/release-process/SKILL.md`. 9 GitHub issues filed for release improvements. Team ready for next cycle. +- 📌 **Team update (2026-03-22T09-35Z — Wave 1):** Ambient personal squad design validated and 19-task implementation plan authored across 4 PRs (Phase 1 SDK, Phase 2 CLI, Phase 3 governance, Phase 4 tests). MVP = PR #1 + PR #3. EECOM executing Phase 1–2 (SDK + CLI), Procedures executing Phase 3 (governance) concurrently. All design gaps resolved; dependency graph established. Procedures wrote governance proposals for personal squad + economy mode — awaiting your review. Sims to execute Phase 4 after Phase 1+2 merge. Directive captured: bug #502 (node:sqlite, P1) to be picked up after Wave 1. No blocking issues — ready for execution. +- Three-branch model (main/dev/insiders). Apollo 13 team, 3931 tests. Boundary review heuristic: "Squad Ships It" — if Squad doesn't ship the code, it's IRL content. Proposal-first: meaningful changes need docs/proposals/ before code. Two-error lockout policy: agent locked out after 2 errors in a session. Test name-agnosticism: framework tests must never depend on dev team's agent names. - **Issue filing pattern:** When a major incident occurs, file 9+ GitHub issues documenting root causes and improvements. One issue per root cause + one per action item. Creates accountability and accelerates fixes. - **Release governance:** Brady established strict governance — Surgeon owns all publishing; strict playbook adherence; CI/CD is top priority; pre-flight gates mandatory before any release tagging. -- **Adoption tracking architecture:** Three-tier opt-in system: Tier 1 (aggregate-only `.github/adoption/`), Tier 2 (opt-in registry), Tier 3 (public showcase ≥5 projects). `.squad/` is team state only. -- **Content triage skill:** "Squad Ships It" litmus test. Triggered by `content-triage` label. Output: boundary analysis, sub-issues for PAO, IRL reference for Scribe. -- **Sprint prioritization:** Rank by: (1) bugs with active user impact, (2) quality/test gaps blocking GA, (3) high-ROI features unblocking downstream work. Interleave stability + velocity. -- **Distributed mesh integration:** Zero code changes. Convention-first additive layer (skills + scripts + docs). 125:1 ratio. mesh.json stays separate from squad.config.ts. -- **Remote squad access:** Three-phase rollout: Phase 1 GitHub Discussions bot (1 day, zero hosting), Phase 2 Copilot Extension via Contents API (1 week), Phase 3 Slack/Teams bot (2 weeks). Must solve `.squad/` context access. +- **Sprint prioritization:** Rank by: (1) bugs with active user impact, (2) quality/test gaps blocking GA, (3) high-ROI features unblocking follow-on work. Interleave stability + velocity. - **PR #331 boundary review:** "Squad Ships It" pattern — remove external infrastructure docs, reframe platform integration docs, keep Squad behavior/config docs. -- **SDK Init Shore-Up PRD:** 6 SDK issues consolidated into 3-phase initiative: Phase 1 fixes gaps (config sync, built-in member exclusion), Phase 2 wires CastingEngine, Phase 3 test matrix. Owners: EECOM + CAPCOM. -- **Ambient personal squad (#329/#344):** 5 gaps identified: resolvePersonalAgents() function, ghost protocol for orchestration log, --team-root scope, squad personal init command, SQUAD_NO_PERSONAL env var. ensureSquadPathTriple() required in resolution.ts to enforce ghost protocol. -- **Release hardening plan:** PUBLISH-README.md rewrite (#564, absorbs #558-560), CI lint rule rejecting non-workspace npm publish (#557), ghost workflow deletion (#562). Lint rule: scan `.github/workflows/*.yml` for `npm publish` without `-w` flag. -- **Issue triage (2026-03-24 — 14 issues):** P0: #590 (getPersonalSquadRoot broken). P1: #610 (broken docs), #591 (hiring wiring). P2: #597, #588, #554. Questions: #589, #494. Deferred: #581 (ADO PRD, blocked until #341). -- **Community PR quality tiers:** Diberry (MSFT-level, architecturally-sound, merge-ready). Joniba (consistently high-quality, matches team standards). Tamir (technically strong, needs proposal-first discipline + monorepo placement guidance). -## Learnings - -### Issue Filing Patterns (2026-03-23 Release Incident) -When a major incident occurs, file 9+ GitHub issues documenting root causes and improvements. Pattern: one issue per root cause + one per action item. Use descriptive titles linking to specific improvements (e.g., "#556 Dependency validation in pre-publish checks"). Let team pick up issues in priority order. This accelerates fixes and creates accountability. - -### Release Governance Directives (2026-03-23) -Brady established strict release governance: (1) Surgeon owns all publishing (not Coordinator); (2) strict adherence to playbook; (3) document problems so they don't recur; (4) CI/CD is top priority; (5) written playbooks for everything; (6) no improvisation. Captured for team memory and enforced in team decisions. - -### Adoption Tracking Architecture -Three-tier opt-in system: Tier 1 (aggregate-only, `.github/adoption/`) ships first; Tier 2 (opt-in registry) designed next; Tier 3 (public showcase) launches when ≥5 projects opt in. `.squad/` is for team state only, not adoption data. Never list individual repos without owner consent. - -### Remote Squad Access -Three-phase rollout: Phase 1 — GitHub Discussions bot with `/squad` command (1 day, zero hosting). Phase 2 — GitHub Copilot Extension via Contents API (1 week). Phase 3 — Slack/Teams bot (2 weeks). Constraint: any remote solution must solve `.squad/` context access. - -### Content Triage Skill -"Squad Ships It" litmus test codified into reusable workflow. Triggered by `content-triage` label. Output: boundary analysis, sub-issues for PAO (doc extraction), IRL reference for Scribe. Content labels: `content:blog`, `content:sample`, `content:video`, `content:talk`. - -### Distributed Mesh Integration -Zero code changes. Skill files in templates/skills/, scripts in scripts/mesh/, docs in features/. mesh.json stays separate from squad.config.ts. Convention-first additive layer — invisible if unused. 125:1 ratio (30 lines of script vs 3,756 lines of deleted federation code). - -### Sprint Prioritization Pattern -Rank by: (1) bugs with active user impact, (2) quality/test gaps blocking GA, (3) high-ROI features unblocking downstream work. Interleave stability (bugs/quality) with velocity (features) across sprint capacity. - -**Updated wisdom.md with 4 patterns + 2 anti-patterns from recent work:** Test name-agnosticism for team rebirths, dynamic filesystem discovery for evolving content, cli-entry.ts unwired command bug pattern, bump-build.mjs version mutation timing, invalid semver formats, git reset data loss. - -**Issue triage attempted for 30 open issues:** Identified 10 unlabeled issues requiring squad assignment. Enterprise Managed User permissions blocked GitHub API label updates via `gh issue edit`. Triage analysis complete: -- SDK issues (#337, #342) → squad:eecom + squad:capcom (init flow + casting engine) -- Personal squad (#343, #344) → squad:flight (architecture territory) -- A2A protocol (#332-336) → squad:flight + domain experts (network, vox, retro, eecom) -- Tooling layers (#330) → squad:eecom + squad:procedures -Manual label application needed by repo owner. - -**SDK Init Shore-Up PRD created:** Consolidated 6 SDK-related issues (#337-342, #340-341) into unified 3-phase initiative at `.squad/identity/prd-sdk-init-shoreup.md`. Root causes: config sync gap, built-in member exclusion (Ralph, @copilot), CastingEngine bypass. Solution: Phase 1 fixes gaps (P1), Phase 2 wires CastingEngine (P1), Phase 3 exercises full test matrix (P2). Estimated 4 sprints to 100% SDK feature parity. Owners: EECOM + CAPCOM (phases 1-2), FIDO + CAPCOM (phase 3). - -📌 **Team update (2026-03-11T01:25:00Z):** Flight completed 30-issue triage + unified SDK Init Shore-Up PRD. CAPCOM + EECOM completed deep technical analysis + implementation roadmap. 5 decisions merged to decisions.md: Phase-based quality improvement program, CastingEngine canonical casting, squad.config.ts as source of truth, Ralph always-included, implementation priority order. - -### Issue Triage & PR Pipeline (2026-03-22) - -**Triaged 6 unlabeled issues:** Assigned to appropriate squad members per domain expertise and team capacity. Applied `next-up` label to 10 priority items (bugs, easy wins, docs improvements). All triaged issues now have clear ownership and next steps. - -**PR Pipeline:** Reviewed and rebased 8 PRs across EECOM, GNC, and PAO. All merged successfully. Key patterns documented for team reuse: -- **az CLI timeouts** (PR #483): External CLI calls need explicit timeouts + fallback handling -- **History race conditions** (PR #480): File operations require mutex + atomic writes + exhaustive tests -- **Signal handling** (PR #486): SIGINT cleanup needs two-layer approach (parent + child cleanup) -- **ESM exports** (PR #474): Node 22 compatibility requires exports map + file existence validation -- **Broken docs links** (PR #487): Automated link validation should be CI gate - -Test coverage expanded: 36 new tests (EECOM) + 4655+ total passing (GNC report). - -**Coordinator actions:** Filed #488 (GitHub auth documentation), created `next-up` label, labeled 10 priority issues for next sprint focus. -📌 **Team update (2026-03-10T12-55-49Z):** Adoption tracking architecture finalized. Three-tier system approved: Tier 1 (aggregate-only, `.github/adoption/`) shipping with PR #326; Tier 2 (opt-in registry) designed for next PR; Tier 3 (public showcase) launches when ≥5 projects opt in. Append-only file governance rule enforced to prevent data loss. Microsoft ampersand style guide adopted for all user-facing documentation. - -### PR #331 Review — Boundary Review Pattern Reinforced (2026-03-10) -Approved PR #331 ("docs: scenario and feature guides from blog analysis") for merge. PAO's boundary review (remove external infrastructure docs, reframe platform features to clarify scope, keep Squad behavior/config docs) was executed correctly. Key decisions: (1) ralph-operations.md and proactive-communication.md deleted — both document infrastructure around Squad, not Squad itself; (2) issue-templates.md reframed to clarify "GitHub feature configured for Squad" not "Squad feature"; (3) reviewer-protocol.md Trust Levels section kept — documents user choice spectrum within Squad's existing review system. Litmus test pattern: if Squad doesn't ship the code/config, it's IRL content. Docs-test sync maintained. Pattern reinforced as reusable boundary review heuristic for future doc PRs. - -**Adoption tracking architecture — three-tier opt-in system:** `.squad/` is for team state only, not adoption data (boundary pattern). Move tracking to `.github/adoption/`. Never list individual repos without owner consent — aggregate metrics only until opt-in exists. Tier 1 (ship now) = aggregate monitoring. Tier 2 (design next) = opt-in registry in `.github/adoption/registry.json`. Tier 3 (launch later) = public showcase once ≥5 projects opt in. Monitoring infra (GitHub Action + script) is solid — keep it. Privacy-first architecture: code search results are public data, but individual listings require consent. - -**Remote Squad access — three-phase rollout:** Phase 1 (ship first): GitHub Discussions bot with `/squad` command. Workflow checks out repo → has full `.squad/` context → answers questions → posts reply. 1 day build, zero hosting, respects repo privacy automatically. Phase 2 (high value): GitHub Copilot Extension — fetches `.squad/` files via GitHub API, answers inline in any Copilot client (VS Code, CLI, mobile). Works truly remote, instant, no cold start. 1 week build. Phase 3 (enterprise): Slack/Teams bot for companies. Webhook + GitHub API fetch. 2 weeks build. Constraint: Squad needs `.squad/` state (team.md, decisions.md, histories, routing) to answer intelligently. Any remote solution must solve context access. GitHub Actions workflows solve this for free (checkout gives full state). Copilot Extension uses Contents API. Discussions wins for MVP because it's async (perfect for knowledge queries), persistent (answers are searchable), and zero infra. Proposal-first: write `docs/proposals/remote-squad-access.md` before building. - -### Content Triage Skill Codified (2026-03-10) -Created `.squad/skills/content-triage/SKILL.md` to codify the boundary heuristic from PR #331. Defines repeatable workflow for triaging external content (blog posts, sample repos, videos, talks) to determine what belongs in Squad's public docs vs IRL tracking. Key components: (1) "Squad Ships It" litmus test — if Squad doesn't ship the code/config, it's IRL content; (2) triage workflow triggered by `content-triage` label or external content reference in issue body; (3) output format with boundary analysis, sub-issues for PAO (doc extraction), and IRL reference entry for Scribe; (4) label convention (`content:blog`, `content:sample`, `content:video`, `content:talk`); (5) Ralph integration for routing to Flight, creating sub-issues, and notifying Scribe. Examples include Tamir blog analysis (PR #331), sample repo with ops patterns, and conference talk. Pattern prevents infrastructure docs from polluting Squad's public docs while ensuring community content accelerates adoption through proper extraction and referencing. -📌 **Team update (2026-03-11T01:27:57Z):** Content triage skill finalized; "Squad Ships It" boundary heuristic codified into shared team decision (decisions.md). Remote Squad access phased rollout approved (Discussions bot → Copilot Extension → Chat bot). PR #331 boundary review pattern established as standard for all doc PRs. Triage workflow enables Flight to scale as community content accelerates. - ---- - -### Issue Triage — 6 Unlabeled Issues Routed (2026-03-20) - -Triaged and labeled 6 unlabeled issues using routing table: - -- **#485 (Agent Specification PRD)** → squad:flight + squad:procedures — Architecture decision (Flight) + formal spec structure (Procedures) -- **#481 (StorageProvider PRD)** → squad:control + squad:eecom — Type system abstraction (CONTROL) + runtime integration (EECOM) -- **#479 (history-shadow race condition)** → squad:eecom + squad:retro — Production data loss bug; mitigation through StorageProvider atomicity -- **#478 (Polish REPL)** → squad:vox + squad:pao — Shell UX readiness (VOX) + README documentation gate (PAO) -- **#477 (Code Quality Linting PRD)** → squad:fido — Monorepo async/promise quality, ESLint 9 PoC ready -- **#476 (Guide v0.4.1 update)** → squad:handbook + squad:pao — SDK patterns + documentation - -Key pattern: PRDs cluster around three architectural gaps (agent spec, state abstraction, quality tooling) + one production bug (#479). Guide update high community value. -### Ambient Personal Squad Architecture Review (#329 + #344) - -**Design validated:** The `flight-ambient-personal-squad.md` proposal is structurally sound. Key finding: `multi-squad.ts` already stores personal squad paths as direct dirs (`squads/{name}/`) with no nested `.squad/` subfolder — the "each team IS the squad root" convention is already the implementation, not a change needed. - -**Five gaps found in the design doc:** -1. No `resolvePersonalAgents()` function signature — added in implementation plan (T2). -2. Scenario 9 contradiction: personal agents wrote to project orchestration log, violating ghost protocol. Resolution: coordinator writes audit trail (project state), not the personal agent. -3. `--team-root` scope was undefined. Decision: additive CLI flag on `squad init`, backward compat with existing `config.json` teamRoot. -4. `squad personal init` was missing — bootstrapping path for first-time users. Added as T6 subcommand. -5. `SQUAD_NO_PERSONAL` env var was in Open Questions but absent from phases. Added to T1. - -**Architecture decision:** Need `ensureSquadPathTriple` in `resolution.ts` (T4) — personal agents write to a third root (personal squad dir). Without it, ghost protocol is advisory-only and not enforced by path guards in SDK. - -**Phasing:** Four PRs. MVP = PR #1 (SDK Foundation) + PR #3 (Governance). Users see ambient cast immediately; `squad personal` commands are quality-of-life on top. - -**Implementation plan written to:** `.squad/decisions/inbox/flight-329-344-implementation-plan.md` - -📌 **Team update (2026-03-24):** Ambient personal squad design reviewed and approved with 5 gaps identified and resolved. Implementation plan broken into 4 PRs across EECOM (SDK + CLI), Procedures (governance), and Sims (tests). MVP path = SDK foundation + governance updates. Phased to avoid one giant PR. - -### Session 2 Summary (2026-03-22) - -Wave 1 architecture work on #329/#344: validated 20KB personal squad design doc, identified and patched 5 gaps, authored 19-task implementation plan spanning 4 future PRs. Implementation not yet started — deferred to future session. EECOM assigned Phase 1–2 (SDK + CLI), Procedures assigned Phase 3 (governance), Sims assigned Phase 4 (tests). - -### Community PR Batch Review — July 2026 - -Five open community PRs reviewed: - -- **#524 (diberry)** — Astro docs improvements (sitemap, RSS, schema fields, ToC component, robots.txt). ✅ Merge-ready. Flag: `robots.txt` Sitemap URL points to `squad.dev` while `astro.config.mjs` still uses `bradygaster.github.io` — minor URL inconsistency to address. -- **#523 (diberry)** — Worktree-aware `detectSquadDir` + `resolveWorktreeMainCheckout` + init guard. ✅ Merge-ready. Directly addresses the worktree gap flagged in #525. Clean implementation; interactive TTY prompt with sensible default. -- **#522 (tamirdresher)** — Rate limiting/circuit breaker watch integration. 🔄 Still a full rewrite of watch.ts. Brady's CHANGES_REQUESTED (additive patch, not full file replacement) has NOT been addressed. Same structural concern remains. -- **#513 (tamirdresher)** — Cross-machine-coordination SKILL.md. 🔄 Wrong directory (`.squad/skills/` is team-state; generic library content belongs in `templates/skills/`). Personal use case examples (voice cloning, DevBox) should be generalized. Needs `docs/proposals/` entry per proposal-first policy. -- **#507 (JasonYeYuhe)** — Chinese README translation. 🔄 Needs a community-maintained freshness disclaimer before merging. Translation quality looks solid; the maintenance burden concern is the only gate. - -**Patterns noted:** -- Diberry (MSFT) is delivering consistent, architecturally-sound contributions — both PRs are merge-ready. -- Tamir's contributions are technically strong but need delivery discipline (full-rewrite vs. surgical patch, proposal-first for new primitives). -- Community translations are welcome but need a sustainability framing before merge. - -### Worktree Gap Triage — #525 (2025-07-18) - -Community contributor joniba filed #525 identifying that Squad has full worktree *detection* but zero worktree *creation* in the coordinator/spawn flow. Validated all 10 claims — analysis is accurate. The reading infrastructure (resolveSquad() worktree detection, .gitattributes merge=union, boundary tests) is ~95% complete. The gap: ralph-commands.ts hardcodes `git checkout -b` in all 3 platform adapters (lines 50/71/92), coordinator never creates worktrees before spawn, no WORKTREE_PATH in prompts, and issue-lifecycle.md is referenced in squad.agent.md but doesn't exist. - -**Decision:** P2 — important but not v1-blocking. Broke into 5 sub-issues: (1) doc fix for missing issue-lifecycle.md (quick win → Procedures), (2) worktree variant in ralph-commands.ts (EECOM), (3) coordinator pre-spawn logic (Procedures + EECOM), (4) post-merge cleanup (EECOM), (5) architecture decision on heuristic (Flight). Sub-issue #1 ships immediately; #2–5 queue post-Wave-1 alongside SubSquads work where parallel execution becomes a hard requirement. - -**Backlog priority recommendation:** Top 5 for v1 = #508 (Ambient Personal Squad), #498 (remove .squad/ from VCS), #485 (Agent Spec & Validation), #481 (Typed StorageProvider), #347 (shore up init --sdk). Quick wins: #525 doc fix, #347. Deprioritize: manual verification debt (#418–421), long-term exploratory. A2A (#332–336) stays shelved per existing decision. - -### Release Hardening Plan — Finalized (2026-07-22) - -Brady approved scope for remaining v0.9.1 incident hardening. Three issues to execute, three deferred into umbrella: - -**DO:** #564 (rewrite PUBLISH-README.md as living playbook — absorbs #558, #559, #560), #557 (CI lint rule rejecting non-workspace `npm publish` in workflow YAML), #562 (delete ghost workflow `publish-npm.yml` ID 250121956). - -**DEFERRED into #564:** #560 (pre-flight checklist → playbook section), #559 (fallback protocol → playbook section), #558 (422 race docs → playbook section). - -**Key findings:** -- GitHub REST API has NO "Delete a workflow" endpoint. Ghost workflows only disappear when all their runs are deleted (GitHub GC). Procedure: `gh api` to list+delete all runs for workflow ID 250121956, then wait for GC. -- The lint rule goes in `squad-ci.yml` as a `publish-policy` job: scans `.github/workflows/*.yml` for `npm publish` without `-w` flag. Blocks PR merge if violated. -- PUBLISH-README.md playbook has 11 sections covering pre-flight, CI publish, manual fallback, 422 race conditions, insider channel, workspace policy, post-publish verification, and version bumping. Replaces the stale v0.8.22 stub entirely. - -**Execution order:** #562 (Brady, manual API call) and #557 (FIDO/Procedures, CI change) run in parallel. #564 (Procedures+Surgeon, playbook) goes last so it can reference the lint rule. +## Recent preserved tail Decision written to `.squad/decisions/inbox/flight-release-hardening-plan.md`. @@ -207,3 +50,8 @@ Decision written to `.squad/decisions/inbox/flight-release-hardening-plan.md`. **Pattern:** Tamir is a high-output contributor (6 PRs in 2 weeks) but needs proposal-first discipline. Joniba and diberry deliver MSFT-level quality. Decision written to `.squad/decisions/inbox/flight-triage-session-plan.md`. + +## 📌 Team update — 2026-08-19T13:11:34.130-07:00 + +Flight's protected-files policy decision is now canonical: Squad's worker default should use `protected-files` object form with `policy: fallback-to-issue` and `exclude: [README.md]`. The guard protects reviewers from high-leverage changes becoming routine agent output; `CHANGELOG.md` remains protected by default. Adoption-time repo configuration should later expose this choice alongside the Actions preflight. + diff --git a/.squad/agents/pao/history.md b/.squad/agents/pao/history.md index 8c8c85ed7..012ea6053 100644 --- a/.squad/agents/pao/history.md +++ b/.squad/agents/pao/history.md @@ -1,238 +1,43 @@ -# PAO +# Pao history -> Public Affairs Officer +Summarized by Scribe on 2026-08-19T13:11:34.130-07:00 because this history exceeded 15KB. +Full pre-summary history archived at `.squad/agents/pao/history-archive-2026-08-19T13-11-34.130-07-00.md`. -## Core Context +## Condensed index -Docs live in docs/ with blog/, concepts/, cookbook/, getting-started/, guide/, features/, scenarios/ sections. Blog tests use filesystem discovery (dynamic); other sections use hardcoded expected arrays. Microsoft Style Guide enforced: sentence-case headings, active voice, second person, present tense. Docs format: plain markdown, H1 title, experimental warning, "Try this" code blocks, overview, HR, H2 content sections. Scannability framework: paragraphs for narrative, bullets for scannable items, tables for comparisons. +- Preserved 315 original line(s) in the archive. +- Detected 41 heading(s) and 17 dated reference line(s). +- This file now keeps a compact index plus the most recent tail so active context remains visible. -## Recent Learnings +## Notable retained signals -### Release Playbook Rewrite (#564, 2026-07-22) -Rewrote PUBLISH-README.md from v0.8.22 stub (58 lines) to living 232-line version-agnostic playbook with 11 sections: Overview, Pre-Flight Checklist, Publish via CI (recommended), workflow_dispatch fallback, Insider Channel, Workspace Publish Policy, Manual Local Publish, 422 Race Condition & npm Errors, Post-Publish Verification, Version Bump, Legacy Scripts. Pattern: living playbook absorbs multiple issues (#558, #559, #560) into unified decision tree. Microsoft Style Guide enforced; `` placeholder; all commands copy-pasteable. - -📌 **Team update (2026-03-24T06-release-hardening):** Release playbook rewrite (#564) completed. Absorbed issues #558, #559, #560 into unified decision tree. - -### JSDoc API Reference PRD (2026-03-24) -Full PRD at `docs/research/jsdoc-api-reference-prd.md`. Key decisions: TypeDoc + typedoc-plugin-markdown (not Starlight, not api-extractor) — zero migration, Markdown-first, Pagefind-compatible. Astro integration hook auto-runs TypeDoc on build. Output → `docs/src/content/docs/reference/api/`. JSDoc improvement priority: config/schema.ts (8%→100%), state/io/ @param/@return tags. Total effort: 13–18 hours. PRD structure: chosen path + tactical roadmap (not advisory — directive). - -### Community Engagement Wave (2026-03-24) -6 discussions closed as resolved (features shipped in v0.9.1: per-agent models #463/#402, local-only #324, CLI vs agent #299, human members #143, skills system #169). 8 discussions kept open with substantive replies. Pattern: feature-release timing + follow-up responses critical for community trust. **Teams MCP critical:** Office 365 Connectors retired Dec 2024 → Power Automate Workflows is successor. Purge all old connector references. - -## Historical Learnings Summary (condensed) - -- **Discussion triage pattern:** When you ship features, search discussions for matching feature-requests → respond + close proactively. Map new features to open discussions; respond with version + docs link; close as resolved; consolidate duplicates; convert bugs/roadmap items to issues. 43% closure rate on resolved items. -- **Docs-test sync:** When adding docs pages, update test assertions in docs-build.test.ts in the SAME commit. When rebasing doc PRs, main branch (already merged) takes priority. +- Rewrote PUBLISH-README.md from v0.8.22 stub (58 lines) to living 232-line version-agnostic playbook with 11 sections: Overview, Pre-Flight Checklist, Publish via CI (recommended), workflow_dispatch fallback, Insider Channel, Workspace Publish Policy, Manual Local Publish, 422 Race Condition & npm Errors, Post-Publish Verification, Version Bump, Legacy Scripts. Pattern: living playbook absorbs multiple issues (#558, #559, #560) into unified decision tree. Microsoft Style Guide enforced; `` placeholder; all commands copy-pasteable. +- 📌 **Team update (2026-03-24T06-release-hardening):** Release playbook rewrite (#564) completed. Absorbed issues #558, #559, #560 into unified decision tree. +- Full PRD at `docs/research/jsdoc-api-reference-prd.md`. Key decisions: TypeDoc + typedoc-plugin-markdown (not Starlight, not api-extractor) — zero migration, Markdown-first, Pagefind-compatible. Astro integration hook auto-runs TypeDoc on build. Output → `docs/src/content/docs/reference/api/`. JSDoc improvement priority: config/schema.ts (8%→100%), state/io/ @param/@return tags. Total effort: 13–18 hours. PRD structure: chosen path + tactical roadmap (not advisory — directive). +- 6 discussions closed as resolved (features shipped in v0.9.1: per-agent models #463/#402, local-only #324, CLI vs agent #299, human members #143, skills system #169). 8 discussions kept open with substantive replies. Pattern: feature-release timing + follow-up responses critical for community trust. **Teams MCP critical:** Office 365 Connectors retired Dec 2024 → Power Automate Workflows is successor. Purge all old connector references. - **Boundary review:** "Squad Ships It" litmus test — if Squad doesn't ship the code, it's IRL content. Platform features: clarify whose feature it is. Delete external infrastructure docs; reframe platform integration docs; keep Squad behavior/config docs. Pattern from PR #331. -- **Astro docs format:** Plain markdown, H1 title, experimental warning callout, "Try this" code blocks at top, overview paragraph, HR, then H2 sections. No Astro frontmatter. DOCS-TEST SYNC mandatory. -- **Scannability framework:** Paragraphs for narrative (3-4 sentences max). Bullets for scannable items. Tables for comparisons. If reader hunts for one item in a paragraph → convert to bullets/table. - **npx purge:** `npm install -g @bradygaster/squad-cli` is only supported install path. Remove all user-facing `npx` references. Keep `npx` only for dev tools (changeset, vitest, astro, pagefind). Agency copilot example → `gh copilot`. -- **README slimming:** README cut from 512 to 331 lines. SDK deep-dive → compact pointer to docs site. README = discovery/orientation; docs site = full reference. -- **Docs catalog audit:** 15 orphaned pages (exist but not in navigation.ts). Stale content: whatsnew.md, insider-program.md. Duplicate/overlap pairs. Booster added automated version sync for whatsnew.md. Nav structure: zero dead links, all orphans reachable internally. -- **PR Trust Model:** Three levels: Full review (default), Selective review (personal projects), Self-managing (solo personal repos only). Self-managing ≠ unmonitored — use Ralph + Teams notifications. -- **JSDoc API Reference Research:** TypeDoc + typedoc-plugin-markdown. Squad SDK 60-80% JSDoc coverage. Research at `docs/research/jsdoc-api-reference-research.md`. Configuration templates, 4-phase roadmap, tool comparison matrix. -- **v0.9.0 blog post format:** YAML frontmatter (title/date/author/wave/tags/status/hero) → experimental warning → "What Shipped" (H2 sections + callout boxes) → "Quick Stats" → "Breaking Changes" → "Upgrading" → "What's Next". 200-400 words for infrastructure releases. EXPECTED_BLOG uses filesystem scan — no test changes needed. - **PR #11 TypeDoc review (2026-03-24):** Generated docs require crosslinks from curated guides. When adding new docs section, ensure old curated page has a visible pointer to the new section. Blocking issues: missing sdk.md crosslink banner, navigation URL inconsistency (`reference/api/index` → `reference/api`). -- **Contributor recognition:** CONTRIBUTORS.md tracks team roster + community contributors. Each release includes recognition updates. Append PR counts, don't replace. -## Learnings - -### Discussion Triage Patterns (2026-03-23 Release Incident) -**Context:** v0.9.1 release completed; 15 open discussions analyzing whether community response patterns matched feature releases. - -**Pattern identified:** Feature releases without follow-up discussion closes = missed trust opportunity. When you ship features (personal squad, worktrees, economy mode, rate limiting), search discussions for matching feature-requests → respond + close proactively. This signals to community that you listen. - -**Triage workflow:** -1. Map new features to open discussions (which discussions are solved by this release?) -2. Respond: "This feature is now available in v0.9.1. See docs link." -3. Close as resolved -4. Consolidate: if discussion #463 is duplicate of #402, merge responses into #402, close #463 -5. Convert: if discussion reveals a bug or roadmap item, convert to issue with label (e.g., squad:eecom) -6. Keep: if discussion is feedback or edge case, keep open; respond substantively - -**For v0.9.1 release:** 4 closed, 1 consolidated, 2 converted to issue, 8 kept. Result: community sees responsiveness; discussions become productivity tool, not backlog. - -**Critical finding:** Teams MCP docs need urgent update — Office 365 Connectors deprecated Dec 2024. Docs must purge old connector references and document Power Automate Workflows path (new successor). - -### Chinese README Workflow (2026-03-23 Release Incident) -Community contributor (PR #572) provided Chinese README translation. Approved and merged as part of v0.9.1 release. Pattern: accept community translations; list contributors in CONTRIBUTORS.md; acknowledge in release notes. - -### Teams MCP Urgency Pattern (2026-03-23) -External tool integrations deprecate. Office 365 Connectors retired Dec 2024. Docs mentioning deprecated tools create support burden and user confusion. Action: audit all external tool integration docs for deprecation; update with successor guidance (Power Automate Workflows for Teams). - -### Blog Post Format -YAML frontmatter: title, date, author, wave, tags, status, hero. Body: experimental warning, What Shipped, Why This Matters, Quick Stats, What's Next. 200-400 words for infrastructure releases. No hype — explain value. - -### Boundary Review Heuristic -"Squad Ships It" litmus test: if Squad doesn't ship the code/config, it's IRL content. Platform features used alongside Squad: clarify whose feature it is. Squad behavior/config docs stay. External infrastructure docs (ralph-operations, proactive-communication) → IRL. - -### DOCS-TEST SYNC -When adding docs pages, update test assertions in docs-build.test.ts in the SAME commit. When rebasing doc PRs, main branch (already merged) takes priority. - -### Contributor Recognition -CONTRIBUTORS.md tracks team roster and community contributors. Each release includes recognition updates. Append PR counts, don't replace. - -### Skill Scope Documentation Pattern -Explicitly state what a skill produces and does NOT produce. Deterministic skills prevent agents from generating unnecessary code when templates exist. - -### Teams MCP Audit -External tool integrations require explicit "where to get it" guidance. Placeholder paths need clarification that users must provide actual MCP server implementations. - -### Cross-Org Authentication Docs -Problem/solution structure for multi-account auth: gh auth switch, Copilot instructions, Squad skill pattern. Cover credential helpers, EMU variations, common error messages. Cross-reference in troubleshooting and enterprise-platforms pages. - -### Roster & Contributor Recognition (v0.8.25) -Squad moved to Apollo 13/NASA Mission Control naming scheme (Flight, Procedures, EECOM, FIDO, PAO, CAPCOM, CONTROL, Surgeon, Booster, GNC, Network, RETRO, INCO, GUIDO, Telemetry, VOX, DSKY, Sims, Handbook). CONTRIBUTORS.md tracks both team roster and community contributors; contributor table entries grow with PRs (append PR counts rather than replace, maintaining attribution history). - -### Git Rebase for Doc Merges -When rebasing doc PRs with conflicts from other merged doc PRs, the main branch version (already merged) should generally take priority. For Node.js version references, maintain LTS terminology when present (e.g., `nvm install --lts` over specific version numbers like `nvm install 20`). Conflict resolution pattern: preserve new content from PR branch only where it doesn't duplicate or contradict already-merged changes. Use `git -c core.editor=true rebase --continue` to bypass interactive editor issues on Windows. - -### Astro Docs Format (v0.8.26) -Squad docs use plain markdown without Astro frontmatter. Structure: title (H1), experimental warning callout, "Try this" code blocks at top, overview paragraph, horizontal rule, then content sections with H2 headings. Microsoft Style Guide enforced: sentence-case headings, active voice, second person ("you"), present tense, no ampersands except in code/brand names. Features and scenarios directories added to test coverage in docs-build.test.ts. Reference implementations linked where available (e.g., ralph-watch.ps1 for operational patterns). - -### Proactive Communication Patterns (v0.8.26) -Two-way communication layer between Squad and work environment. Outbound: Teams webhook notifications (breaking, briefings, recaps, flashes) sent via Adaptive Cards — only when newsworthy. Inbound: WorkIQ/Playwright scanning of Teams channels and email → auto-create GitHub issues with teams-bridge label, anti-duplicate logic enforced. Loop: inbound creates issues → Ralph dispatches → agents work → outbound notifies results. Human stays informed on mobile. Prerequisites are enhancements, not requirements. - -📌 **Team update (2026-03-11T01:27:57Z):** Proactive communication patterns and PR trust levels (full/selective/self-managing spectrum) documented in decisions.md. Pattern rationale reinforced: Ralph 24/7 autonomous deployment requires awareness loop (Teams webhooks for outbound) and external work integration (WorkIQ scanning for inbound). Trust levels enable context-appropriate oversight without bottlenecking teams. - -### PR #487 Review & Merge — CLI Docs Expansion (2026-03-22) - -Reviewed and merged PR #487 (CLI documentation expansion + broken docs link fix). Improved CLI command reference coverage and fixed internal link validation. - -**Pattern identified:** Broken internal links hurt user navigation and SEO. Recommendations: (1) add link validation to docs build pipeline (crawl all internal references, report 404s), (2) make validation a CI gate (fail build on broken links), (3) maintain link checklist when refactoring docs structure. - -**Key learning:** Documentation maintenance requires systematic link validation. A single broken link creates friction for users following guides. Automated validation should be non-negotiable in CI/CD. - -### PR #482 Review & Merge — Pagefind Search Integration (2026-03-22) - -Reviewed and merged PR #482. Search functionality integrated into docs site for improved discoverability. - -### PR #11 Docs Quality Review — TypeDoc API Reference (2026-03-24) - -**Status:** REQUEST CHANGES (3 fixes required, 2 recommended) - -**Key findings:** -- **Research + PRD:** Excellent quality. Clear problem statement, realistic effort estimate, pragmatic tool choice (TypeDoc over Starlight/api-extractor). Scannability framework applied correctly (tables for audit data, bullets for findings, paragraphs for narrative). -- **Navigation strategy:** Collapsible `
` approach for 395-page API reference is sound UX. Sidebar nav plan well-structured with clear open questions about CI/CD safety. -- **Microsoft Style compliance:** Mostly strong; discovered 3 minor issues. - -**Issues found:** -1. **🔴 Blocking:** sdk.md crosslink banner missing. Users navigating from curated "SDK" guide have no callout to the auto-generated "API Reference". Add "See Also" link in sdk.md before "## Resolution" section. -2. **🔴 Blocking:** Navigation URL inconsistency. `navigation.ts` hardcodes `reference/api/index` when it should be `reference/api` — Astro resolves `/api/` to `/api/index` automatically. Simplify slug. -3. **🟡 Blocking:** Nav plan's "Open Questions" section asks about CI/CD fallback (generated JSON missing). Plan should either specify build order (`docs:api` before `docs build`) or provide fallback empty nav for fresh clones. -4. **🟡 Recommended:** 2–3 test descriptions need more specificity (e.g., "class page renders heading and content" → "class page renders method signatures and definition source"). -5. **🟡 Recommended:** Screenshot filenames don't align with skill convention. Use semantic names: `api-reference-landing`, `api-class-detail`, `api-function-detail`. - -**Pattern identified:** Generated documentation requires crosslinks from curated guides. When adding a new docs section (API reference, CLI reference, etc.), ensure the *old* curated page (SDK Guide) has a visible pointer to the new section. This prevents users from stopping at the curated version and missing the comprehensive auto-generated reference. - -**Effort to fix:** < 2 hours. All issues are surgical edits to existing content; no architectural changes needed. - -### PR #484 Review & Merge — Sample READMEs (2026-03-22) - -Reviewed and merged PR #484. Sample README templates added to improve consistency across documentation examples. - -### PR Trust Model Documentation (v0.8.26) -Three trust levels for PR management: (1) Full review (default, team repos) — human gate on every merge; (2) Selective review (personal projects with patterns) — human reviews only critical paths; (3) Self-managing (solo personal repos only) — Squad merges own PRs, human reviews retroactively. Added to reviewer-protocol.md as new section. Important: self-managing ≠ unmonitored; use Ralph work monitoring and Teams notifications for awareness. Decision matrix included for when to use each level. - -### Final Docs Review Pattern (v0.8.26) -Pre-PR quality reviews check: (1) Microsoft Style Guide compliance (sentence-case headings, active voice, no ampersands, present tense, second person); (2) Tone consistency (practical, developer-focused, no hype); (3) Technical accuracy (code examples, file paths, commands); (4) Cross-reference integrity (valid links between pages); (5) DOCS-TEST SYNC (test assertions match new pages); (6) Privacy directive compliance (no individual repos without consent). Fixed duplicate section heading in reviewer-protocol.md (merge artifact). All staged docs passed review and are ready to commit. - -### Squad vs IRL Boundary Review (v0.8.26) -Evaluated four docs pages from PR #331 (Tamir's blog analysis) against Squad-specificity criterion: does content document Squad features/patterns (belongs in Squad docs) or community implementation examples (belongs in Squad IRL)? Key distinction: Squad docs = "how the feature works + universal best practices" vs IRL = "how one person built an amazing setup." Results: ralph-operations.md borderline (deployment wrappers are external infrastructure, not Squad features — trim "outer loop" framing), issue-templates.md borderline (GitHub feature documented for Squad context, not Squad code — clarify scope), proactive-communication.md does not belong (community extension pattern using WorkIQ/Playwright, not built into Squad), reviewer-protocol.md trust levels section belongs (documents user choice spectrum within Squad's existing review system). Pattern: if Squad doesn't ship the code, it's IRL content; if it's a GitHub platform feature used alongside Squad, clarify that distinction; if it documents actual Squad behavior/configuration, it belongs. - -### Boundary Review Execution (v0.8.26) -Executed boundary review findings from PR #331: (1) Deleted ralph-operations.md (infrastructure around Squad, not Squad itself — moved to IRL); (2) Deleted proactive-communication.md (external tools/webhooks — moved to IRL); (3) Reframed issue-templates.md intro to clarify "GitHub feature configured for Squad" not "Squad feature"; (4) Updated EXPECTED_SCENARIOS in docs-build.test.ts to match remaining files. Pattern reinforced: boundary review = remove external infrastructure docs, reframe platform integration docs to clarify whose feature it is, keep Squad behavior/config docs. Changes staged for commit. - -### Cross-Org Authentication Docs (v0.8.26) -Created docs/src/content/docs/scenarios/cross-org-auth.md covering GitHub personal + Enterprise Managed Users (EMU) multi-account auth. Three solutions documented: (1) gh auth switch for manual account toggling; (2) Copilot instructions (.github/copilot-instructions.md) for account mapping documentation; (3) Squad skill pattern for auth error detection and recovery. Covered git credential helpers (per-host and per-org), EMU hostname variations (github.com vs dedicated instances), and common error messages (HTTP 401, authentication required). Added cross-references in troubleshooting.md (new section), enterprise-platforms.md (authentication section), and navigation.ts. Updated test/docs-build.test.ts with 'cross-org-auth' in EXPECTED_SCENARIOS. Pattern: Microsoft Style Guide (sentence-case), "Try this" prompts at top, problem/solution structure, practical examples over abstractions, links to related pages at bottom. - -### Scannability Framework (v0.8.25) -Format selection is a scannability decision, not style preference. Paragraphs for narrative/concepts (3-4 sentences max). Bullets for scannable items (features, options, non-sequential steps). Tables for comparisons or structured reference data (config, API params). Quotes/indents for callouts/warnings. Decision test: if reader hunts for one item in a paragraph, convert to bullets/table. This framework is now a hard rule in charter under SCANNABILITY REVIEW. - -### Docs Catalog Audit (2026) -Full audit of the Astro-based docs site. Key patterns and findings: - -**Orphaned pages (exist but not in navigation.ts):** 15 total — `get-started/choose-your-interface.md`, `guide/faq.md`, `guide/build-autonomous-agent.md`, `guide/github-auth-setup.md`, `features/built-in-roles.md`, `features/context-hygiene.md`, `features/cost-tracking.md`, `features/issue-templates.md`, `reference/vscode-troubleshooting.md`, and 6 root-level legacy files (`guide.md`, `sample-prompts.md`, `tips-and-tricks.md`, `tour-first-session.md`, `tour-github-issues.md`, `tour-gitlab-issues.md`). - -**Stale content:** `whatsnew.md` reports v0.8.2 as current; actual is v0.8.26+. `insider-program.md` uses deprecated `npx github:` install format and references old `.ai-team/` directory name throughout. - -**Duplicate/overlap pairs:** `choosing-your-path.md` (in nav) vs `choose-your-interface.md` (orphan, more complete); root-level `sample-prompts.md` vs `guide/sample-prompts.md`; root-level `tips-and-tricks.md` vs `guide/tips-and-tricks.md`; root-level `tour-first-session.md` vs `get-started/first-session.md`. - -**Content quality:** All actively-navved pages are well-written, follow Microsoft Style Guide, and use correct install commands. Format standards (H1, experimental callout, "Try this" block, HR, H2 sections) are inconsistently applied — some orphaned pages like `built-in-roles.md` and `cost-tracking.md` lack the standard header/callout pattern. - -**Structural issues:** `features/team-setup.md` has a duplicate `## How Init Works` heading (merge artifact). `features/streams.md` nav title is "Streams" but H1 is "Squad SubSquads" (mismatch). `guide/faq.md` is a high-value page completely invisible from the sidebar. `features/built-in-roles.md` is a comprehensive roles reference also invisible from nav. - -**Gap:** No dedicated FAQ entry point, no changelog page, cookbook section is thin (one page), no user-facing explanation of the NASA Mission Control naming scheme for agents. - -**Navigation:** Zero dead nav links (every nav slug has a matching file). All orphan pages are linked internally from other pages so they are reachable — but not browseable via sidebar. - -📌 **Team update (2026-03-22T12:46:00Z):** Booster implemented automated version sync for `whatsnew.md` (finding #1). Script reads `package.json` version, updates "Current Release" heading on every prebuild, with Vitest test gate. Heading now correct (v0.8.25+), will stay in sync automatically on all future builds. Finding #1 resolved. - -### JSDoc API Reference Research (2026-03-23) - -Completed research on generating JSDoc-based API reference documentation for Squad SDK. Key findings: - -**Current State:** Squad SDK has 60–80% JSDoc coverage across major modules (state: 81%, config: 8%). 136 TypeScript source files, no existing TypeDoc config. - -**Tool Recommendation:** **TypeDoc + typedoc-plugin-markdown** — no Starlight migration needed. Seamless integration with existing Astro 5 + Tailwind 4 + Pagefind. Markdown output drops directly into content collections. Auto-generates via Astro integration hook on `npm run build`. - -**Alternatives Evaluated:** -- ❌ Starlight migration: would break existing docs structure and custom branding -- ❌ api-extractor: overkill for open-source SDK; designed for strict monorepo contracts - -**Effort Estimate:** 5–6 hours (setup only) → 13–18 hours (setup + JSDoc improvements) → 15–22 hours (with CI/CD automation). - -**StorageProvider & State Module:** Phase 2 state layer is API-docs ready (81% coverage, well-structured types, clear interface contract). Gaps: add @param/@return tags to state/io functions. - -**URL Structure:** `/api/classes/squad-coordinator/`, `/api/interfaces/storage-provider/`, etc. Pagefind indexes automatically. - -**Deliverable:** Full research at `docs/research/jsdoc-api-reference-research.md` with configuration templates, implementation roadmap (4 phases), and tool comparison matrix. Decision summary at `.squad/decisions/inbox/pao-jsdoc-research.md`. - -### Issue Triage (2026-03-22T06:44:01Z) - -**Flight triaged 6 unlabeled issues and filed 1 new issue.** - -PAO assigned: -- **#488 (GitHub auth setup for project boards)** → squad:pao (documentation, newly filed) -- **#478 (Polish REPL)** → squad:vox + squad:pao (shell UX readiness + README documentation gate) -- **#476 (Guide v0.4.1 update)** → squad:handbook + squad:pao (SDK patterns + documentation) - -New issue #488 is documentation-focused; Fleet relabeled from squad:fido → squad:pao for proper domain ownership. - -📌 **Team update (2026-03-22T06:44:01Z):** Flight issued comprehensive triage. PAO owns GitHub auth docs (#488), REPL documentation gate (#478), and Guide v0.4.1 refresh (#476). High community value on Guide update. Ready to begin documentation work on next sprint. -### npx Purge + Agency Audit -Brady's distribution directive: `npm install -g @bradygaster/squad-cli` is the only supported install path. Remove ALL user-facing `npx @bradygaster/squad-cli` and `npx github:bradygaster/squad` references from docs. Replace with either `npm install -g` (for install steps) or `squad ` (for usage steps). Keep `npx` only for dev tools (changeset, vitest, astro, pagefind). Keep historical blog posts as-is. Migration.md "Before" column and CI/CD "OLD" examples are valid historical context — keep them. Insider program: `npm install -g @bradygaster/squad-cli@insider` and `squad upgrade` replace the old `npx github:bradygaster/squad#insider`. Agency audit: all "agency-agents" references in source files and docs are MIT attribution for the upstream open-source project — legally required, never touch them. The `agency copilot` example in cli-entry.ts help text was a competing-product reference — changed to `gh copilot`. - -### README Slimming + Upgrade Section (v0.8.x) -Brady directive: README was too long at 512 lines. Cut the SDK deep-dive block (custom tools, hook pipeline, Ralph API code) and replaced it with a compact pointer to the docs site. Added a dedicated "Upgrading" section (two-step: `npm install -g` then `squad upgrade`) after Quick Start. Final length: 331 lines. SDK internals live in `docs/src/content/docs/reference/sdk.md` and `tools-and-hooks.md`. The README is now discovery/orientation; the docs site is the full reference. - -### v0.9.0 Release Blog Post (2026-03-23) -Created `docs/src/content/blog/028-v090-whats-new.md` documenting Squad's biggest release: Personal Squad (ambient agent discovery + Ghost Protocol), Worktree Spawning (isolated branches per issue), Machine Capability Discovery (needs:* label routing), Cooperative Rate Limiting (predictive circuit breaker), Economy Mode (budget-aware model selection), Auto-Wired Telemetry, P0 upgrade fixes, and docs refresh. Blog format: frontmatter (title/date/author/wave/tags/status/hero) → experimental warning → "What Shipped" (10 features with H2 sections + callout boxes) → "Quick Stats" → "Breaking Changes" (none) → "Upgrading" → "What's Next". Messaging: clear, engaging, factual (no marketing fluff). Demonstrated: Personal Squad governance layer, worktree isolation, capability declaration, RAAS traffic-light pattern, economy fallback logic. Docs refresh section emphasized: README from 512→218 lines, dedicated upgrade guide, npx purged, Astro features, Teams MCP refresh, autonomous agents guide. Contributors: diberry (worktree tests + docs), wiisaacs (security review), community. No breaking changes — all additive opt-in features. Test discovery is dynamic (EXPECTED_BLOG uses filesystem scan), so new post auto-discovered; no test file changes needed. Pattern reinforced: each feature needs a story — if you can't explain it, it's not ready. Demos over descriptions (concrete code examples, YAML config blocks, Bash CLI examples). - -### Discussion Triage (2026-03-23) - -Analyzed 15 open discussions for response strategy: -- **4 close-as-resolved** (#143, #169 — features now shipped; #402, #299 — answered with docs links) -- **1 close-as-duplicate** (#463 → #402) -- **2 convert-to-issue** (#161 root-copilot-hijack → bug/UX track; #534 enterprise-features → ongoing roadmap signal) -- **8 keep-open** (ongoing feedback, feature signals, edge cases, follow-up potential) - -Key pattern: 15 discussions = 7 feature-request/feedback signals, 4 answered-by-feature-release, 4 documentation-clarity gaps. Community is engaged; v0.9.1 (per-agent models, skills system, human team members, watch mode) directly addressed 5+ discussions that were open for 2-4 weeks. Timing of releases + follow-up responses critical for community trust. - -**Documentation gaps identified:** -- #440 (branch naming convention change) — needs migration guide in upgrade docs -- #306 (multi-root workspaces) → future feature; docs should clarify current limitation -- #140 (Teams MCP + Office 365 Connectors retirement) → docs refresh needed; Power Automate Workflows is the new path -- #401 (mobile/remote control) → feature exploration, keep on radar -- #161 (Coordinator hijacking) → document workarounds, prioritize UX fix for v1.0 - -Teams MCP critical update: Office 365 Connectors retired Dec 2024 → Power Automate Workflows is successor. Docs mention of old Connectors should be purged; Teams webhook examples should link to Power Automate Workflow guide. - -### Community Engagement Wave (2026-03-24) +- ### Discussion Triage Patterns (2026-03-23 Release Incident) +- **Triage workflow:** +- **Critical finding:** Teams MCP docs need urgent update — Office 365 Connectors deprecated Dec 2024. Docs must purge old connector references and document Power Automate Workflows path (new successor). +- ### Chinese README Workflow (2026-03-23 Release Incident) +- Community contributor (PR #572) provided Chinese README translation. Approved and merged as part of v0.9.1 release. Pattern: accept community translations; list contributors in CONTRIBUTORS.md; acknowledge in release notes. +- External tool integrations deprecate. Office 365 Connectors retired Dec 2024. Docs mentioning deprecated tools create support burden and user confusion. Action: audit all external tool integration docs for deprecation; update with successor guidance (Power Automate Workflows for Teams). +- Explicitly state what a skill produces and does NOT produce. Deterministic skills prevent agents from generating unnecessary code when templates exist. +- External tool integrations require explicit "where to get it" guidance. Placeholder paths need clarification that users must provide actual MCP server implementations. +- When rebasing doc PRs with conflicts from other merged doc PRs, the main branch version (already merged) should generally take priority. For Node.js version references, maintain LTS terminology when present (e.g., `nvm install --lts` over specific version numbers like `nvm install 20`). Conflict resolution pattern: preserve new content from PR branch only where it doesn't duplicate or contradict already-merged changes. Use `git -c core.editor=true rebase --continue` to bypass interactive editor issues on Windows. +- Two-way communication layer between Squad and work environment. Outbound: Teams webhook notifications (breaking, briefings, recaps, flashes) sent via Adaptive Cards — only when newsworthy. Inbound: WorkIQ/Playwright scanning of Teams channels and email → auto-create GitHub issues with teams-bridge label, anti-duplicate logic enforced. Loop: inbound creates issues → Ralph dispatches → agents work → outbound notifies results. Human stays informed on mobile. Prerequisites are enhancements, not requirements. +- 📌 **Team update (2026-03-11T01:27:57Z):** Proactive communication patterns and PR trust levels (full/selective/self-managing spectrum) documented in decisions.md. Pattern rationale reinforced: Ralph 24/7 autonomous deployment requires awareness loop (Teams webhooks for outbound) and external work integration (WorkIQ scanning for inbound). Trust levels enable context-appropriate oversight without bottlenecking teams. +- ### PR #487 Review & Merge — CLI Docs Expansion (2026-03-22) +- Reviewed and merged PR #487 (CLI documentation expansion + broken docs link fix). Improved CLI command reference coverage and fixed internal link validation. +- **Pattern identified:** Broken internal links hurt user navigation and SEO. Recommendations: (1) add link validation to docs build pipeline (crawl all internal references, report 404s), (2) make validation a CI gate (fail build on broken links), (3) maintain link checklist when refactoring docs structure. +- **Key learning:** Documentation maintenance requires systematic link validation. A single broken link creates friction for users following guides. Automated validation should be non-negotiable in CI/CD. +- ### PR #482 Review & Merge — Pagefind Search Integration (2026-03-22) +- Reviewed and merged PR #482. Search functionality integrated into docs site for improved discoverability. + +## Recent preserved tail -**6 discussions closed as resolved:** -- #463, #402 (per-agent model selection — shipped v0.9.1) -- #324 (local-only operation without GitHub integration) -- #299 (CLI vs Copilot agent — both viable) - #143 (Human team members now first-class feature) - #169 (Skills system shipped as core infrastructure) diff --git a/.squad/agents/procedures/history.md b/.squad/agents/procedures/history.md index 4f28c82ee..1298528a8 100644 --- a/.squad/agents/procedures/history.md +++ b/.squad/agents/procedures/history.md @@ -1,154 +1,43 @@ -# Procedures +# Procedures history -> Standard Operating Procedures & Spec Writer +Summarized by Scribe on 2026-08-19T13:11:34.130-07:00 because this history exceeded 15KB. +Full pre-summary history archived at `.squad/agents/procedures/history-archive-2026-08-19T13-11-34.130-07-00.md`. -## Learnings +## Condensed index -### Issue Triage (2026-03-22T06:44:01Z) +- Preserved 231 original line(s) in the archive. +- Detected 16 heading(s) and 19 dated reference line(s). +- This file now keeps a compact index plus the most recent tail so active context remains visible. -**Flight triaged 6 unlabeled issues and filed 1 new issue.** +## Notable retained signals -Procedures assigned: - **#485 (Agent Specification PRD)** → squad:flight + squad:procedures (architecture decision + formal spec structure) - -Pattern: Agent specification gap identified. Procedures owns formal spec structure and documentation; Flight owns architecture decisions. - -📌 **Team update (2026-03-26T06:41:00Z — Crash Recovery Execution & Model Catalog Merge):** Procedures executed Round 2 PR merge action: rebased PR #619 (model catalog refresh, issue #588) onto dev branch from main, resolved 3 merge conflicts, and successfully merged. Model catalog now current: default model bumped to `claude-sonnet-4.6` (latest standard-tier Claude), specialist bumped to `gpt-5.3-codex` (latest code-writing specialist), fallback chains restructured to include new models (`gpt-5.4`, `gpt-5.4-mini`) and removed dead models (`claude-opus-4.6-fast`). All 6 original merge-plan PRs (#620, #627, #624, #611, #617, #619) now ✅ complete. Dev branch green (5,038 tests). Decision inbox merged to decisions.md and deleted. Next: Ready for follow-on feature PRs. - -📌 **Team update (2026-03-22T06:44:01Z):** Flight issued comprehensive triage. Procedures owns Agent Specification PRD structure (#485). Architecture decisions from Flight. Coordinate on formal spec format and standard structure for future agent definitions. - -## Historical Learnings Summary (condensed 2026-03-10 → 2026-04-17) - +- Pattern: Agent specification gap identified. Procedures owns formal spec structure and documentation; Flight owns architecture decisions. +- 📌 **Team update (2026-03-26T06:41:00Z — Crash Recovery Execution & Model Catalog Merge):** Procedures executed Round 2 PR merge action: rebased PR #619 (model catalog refresh, issue #588) onto dev branch from main, resolved 3 merge conflicts, and successfully merged. Model catalog now current: default model bumped to `claude-sonnet-4.6` (latest standard-tier Claude), specialist bumped to `gpt-5.3-codex` (latest code-writing specialist), fallback chains restructured to include new models (`gpt-5.4`, `gpt-5.4-mini`) and removed dead models (`claude-opus-4.6-fast`). All 6 original merge-plan PRs (#620, #627, #624, #611, #617, #619) now ✅ complete. Dev branch green (5,038 tests). Decision inbox merged to decisions.md and deleted. Next: Ready for follow-on feature PRs. +- 📌 **Team update (2026-03-22T06:44:01Z):** Flight issued comprehensive triage. Procedures owns Agent Specification PRD structure (#485). Architecture decisions from Flight. Coordinate on formal spec format and standard structure for future agent definitions. - **Deterministic skill pattern (2026-03-10):** Skills must have explicit SCOPE (what they produce/don't) and AGENT WORKFLOW (deterministic steps with STOP condition). Same input → same output, every time. -- **Self-contained skills (2026-03-15):** Resources (scripts, examples, configs) live WITH the skill directory, not in separate template dirs. Agents copy resources from the skill; no manual steps. - **Three governance policies (2026-03-15):** Agent Error Lockout (2 errors → reassign), Product Isolation Rule (tests/CI/code never depend on squad names), Peer Quality Check (run tests before finishing). Applied to all 19 charters. - **Team-wide reskill (2026-03-16):** 17.4% size reduction — NEVER/ALWAYS sections compress to single-paragraph summaries; essential workflow details stay verbose. -- **Economy mode skill (2026-03-22):** Layer 3 modifier only — never downgrades Layers 0-2 (user intent). `💰` indicator in spawn acknowledgments. Session phrase, persistent config, or CLI flag activation. - **Personal squad governance (2026-03-22):** `CONSULT_MODE: true` as spawn signal. Governance changes go to `decisions/inbox/` for Flight review — don't edit squad.agent.md directly. -- **Spawn template `name` fix (2025-07):** Every `task` tool spawn MUST include `name` set to agent's lowercase cast name. Without it, platform defaults to generic slugs. -- **Model catalog refresh (2025-07 / 2026-03-25):** Model catalogs drift. Search ALL model name strings when refreshing — not just the catalog list. Sync via `sync-templates.mjs` to all 5 copies. - **VS Code routing investigation (2026-03-25):** CLI-centric enforcement language causes coordinator to work inline in VS Code. Fix: platform-neutral dispatch language + reinforcement at prompt bottom. - **VS Code routing fix (2026-07):** Fix 1 + Fix 2 shipped. CRITICAL RULE rewritten to dispatcher-identity framing ("DISPATCHER, not a DOER") with dispatch mechanism table. Routing Enforcement Reminder added as final section. Remaining P1 fixes (template renaming, prompt slimming) deferred. - **PR #619 rebase (2026-07):** When a PR has accumulated dev merge commits, use `git rebase --onto dev ` to cherry-pick only relevant commits. - **Trim copilot-instructions.md (#999, 2026-04-17):** 1300w/9KB → 397w/3KB. Extracted Protected Files to skill, consolidated Git Safety, removed duplication. Pattern: main instructions = routing/workflow; skills = domain-specific reference (lazy-loaded on demand). -# Procedures — Project History - -> Learnings, patterns, and context for the Prompt Engineer. - -## Learnings - -📌 **Team update (2026-03-22T09-35Z — Wave 1):** Economy mode governance proposal and personal squad consult-mode governance proposal authored for squad.agent.md — both DRAFT, awaiting Flight review before merging. Economy mode adds Layer 3 table + spawn convention (`💰 economy`) + model catalog audit. Personal squad adds consult mode detection, path reference table, spawn guidance. Persistent model preference (Layer 0) documented. Proposed new skill: `.squad/skills/consult-mode/SKILL.md` (post-approval). Deterministic skill pattern proven effective. PR #503 open with skills module. Next: Flight review → merge governance to squad.agent.md. No blocking issues. - -### 2026-03-10: Deterministic skill pattern - -**Problem:** Skills were too loose. The distributed-mesh skill was tested in a real project (mesh-demo), and agents generated 76 lines of validator code, 5 test files with 43 tests, regenerated sync scripts that should have been copied from templates, and left decision files empty. The skill document let agents interpret intent instead of following explicit steps. - -**Solution:** Rewrite skills to be fully deterministic: - -1. **SCOPE section** (right after frontmatter, before Context) - - ✅ THIS SKILL PRODUCES — exact list of files/artifacts - - ❌ THIS SKILL DOES NOT PRODUCE — explicit negative list to prevent scope creep - -2. **AGENT WORKFLOW section** — Step-by-step deterministic instructions - - ASK: exact questions to ask the user - - GENERATE: exactly which files to create, with schemas - - WRITE: exactly which decision entry to write, with template - - TELL: exact message to output to user - - STOP: explicit stopping condition, with negative list of what NOT to do - -3. **Fix ambiguous language:** - - "do the task" → clarify this means "the agent's normal work" not "build something for the skill" - - "Agent adds the field" → clarify this describes what a consuming agent does with data it READ - - Phase descriptions → note that phases are project-level decisions, not auto-advanced - -4. **Decision template** — inline markdown showing exactly what to write - -5. **Anti-patterns for code generation** — explicit list of things NOT to build - -**Pattern for other skills:** All skills should have SCOPE (what it produces, what it doesn't) and AGENT WORKFLOW (deterministic steps with STOP condition). Same input → same output, every time. Zero ambiguity. - -📌 Team update (2026-03-14T22-01-14Z): Distributed mesh integrated with deterministic skill pattern — decided by Procedures, PAO, Flight, Network - -### 2026-03-15: Self-contained skills pattern (agent-skills spec) - -**Problem:** The distributed-mesh skill had a manual gap — Step 4 told the user to copy sync scripts from templates/mesh/ manually. This violated the GitHub agent-skills spec, which says: "add scripts, examples or other resources to your skill's directory. The skill instructions should tell Copilot when, and how, to use these resources." - -**Solution:** Skills are self-contained bundles. Resources live WITH the skill, not in separate template directories: - -1. **Bundle resources IN the skill directory:** Copy `sync-mesh.sh`, `sync-mesh.ps1`, and `mesh.json.example` into `.squad/skills/distributed-mesh/` -2. **Update SKILL.md workflow:** - - Step 2: Reference `mesh.json.example` from THIS skill's directory - - Step 3: COPY sync scripts from THIS skill's directory to project root (agent does it, not user) - - Step 4: RUN `--init` if Zone 2 state repo specified (agent does it, not user) -3. **Update SCOPE section:** Clarify the skill PRODUCES the copied scripts (bundled resources ≠ generated code) -4. **Replicate to templates:** Copy entire skill directory to `templates/skills/`, `packages/squad-cli/templates/skills/`, `packages/squad-sdk/templates/skills/` - -**Pattern for all skills:** Skills are self-contained. Scripts, examples, configs, and resources travel WITH the skill. The agent reads SKILL.md, sees "copy X from this directory," and does it. Zero manual steps. - -### 2026-03-15: Three new governance policies added to agent system +- 📌 **Team update (2026-03-22T09-35Z — Wave 1):** Economy mode governance proposal and personal squad consult-mode governance proposal authored for squad.agent.md — both DRAFT, awaiting Flight review before merging. Economy mode adds Layer 3 table + spawn convention (`💰 economy`) + model catalog audit. Personal squad adds consult mode detection, path reference table, spawn guidance. Persistent model preference (Layer 0) documented. Proposed new skill: `.squad/skills/consult-mode/SKILL.md` (post-approval). Deterministic skill pattern proven effective. PR #503 open with skills module. Next: Flight review → merge governance to squad.agent.md. No blocking issues. +- **Problem:** Skills were too loose. The distributed-mesh skill was tested in a real project (mesh-demo), and agents generated 76 lines of validator code, 5 test files with 43 tests, regenerated sync scripts that should have been copied from templates, and left decision files empty. The skill document let agents interpret intent instead of following explicit steps. +- ❌ THIS SKILL DOES NOT PRODUCE — explicit negative list to prevent scope creep +- 2. **AGENT WORKFLOW section** — Step-by-step deterministic instructions +- WRITE: exactly which decision entry to write, with template +- STOP: explicit stopping condition, with negative list of what NOT to do +- Phase descriptions → note that phases are project-level decisions, not auto-advanced +- 4. **Decision template** — inline markdown showing exactly what to write +- 5. **Anti-patterns for code generation** — explicit list of things NOT to build +- **Pattern for other skills:** All skills should have SCOPE (what it produces, what it doesn't) and AGENT WORKFLOW (deterministic steps with STOP condition). Same input → same output, every time. Zero ambiguity. +- 📌 Team update (2026-03-14T22-01-14Z): Distributed mesh integrated with deterministic skill pattern — decided by Procedures, PAO, Flight, Network +- 2. **Update SKILL.md workflow:** + +## Recent preserved tail -**Task:** Brady directive — implement three new policies across the agent system: - -1. **Agent Error Lockout** — Added to squad.agent.md. After 2 cumulative errors (build/test failures or reviewer rejection) on the same task, agent is locked out for that task only. Different agent takes over. Coordinator tracks and enforces; Scribe logs lockout events. - -2. **Product Isolation Rule** — Added to every charter and squad.agent.md Constraints. Tests, CI, and product code must NEVER depend on specific agent names from any squad. "Our squad" must not impact "the squad." Use generic/parameterized values (e.g., "test-agent-1") instead of real agent names (Flight, EECOM, FIDO). - -3. **Peer Quality Check** — Added to every charter. Before finishing work, agents must verify their changes don't break existing tests. Run test suite for files touched. Update history.md when learning from mistakes. - -**Implementation:** Updated `.github/agents/squad.agent.md` (new section + constraint) and all 19 active agent charters in `.squad/agents/*/charter.md`. - -**Pattern:** Policies added as subsections under "How I Work" in charters to ensure they're loaded with agent context. Coordinator-level policies live in squad.agent.md with explicit enforcement instructions. - -### 2026-03-16: Team-wide reskill — 17.4% reduction - -**Context:** Routine maintenance reskill, one day after previous reskill (2026-03-15). Last reskill brought the system from 117.4KB to 51.7KB. This pass focused on remaining oversized charters. - -**Work done:** -- **Scribe (2143→1557):** Compressed workflow steps, kept essential commit instructions -- **Handbook (1807→1529):** Removed repetitive LLM-FIRST DOCS emphasis -- **FIDO (1715→1370):** Consolidated verbose NEVER/ALWAYS sections -- **Booster (1583→1368):** Same NEVER/ALWAYS compression pattern - -**Results:** 26,721→17,088 bytes (charters), 28,602→28,602 bytes (histories), total 55,323→45,690 bytes. 9,633 bytes saved (17.4% reduction). All charters now ≤1.5KB. - -**Skill extraction:** No new patterns extracted. CastingEngine integration work (from EECOM March 15) is still evolving — not yet mature enough for skill template. Histories all <12KB, no compression needed. - -**Pattern:** NEVER/ALWAYS sections in charters compress well — fold bullet lists into single-paragraph summaries. Essential workflow details (Scribe's commit steps) should stay verbose. - -### 2026-03-22: Economy mode skill and personal squad governance (#500, #344) - -**Task:** Two governance tasks — economy mode skill design and personal squad coordinator awareness. - -**Economy mode (SKILL.md):** -- Created `.squad/skills/economy-mode/SKILL.md` as a Layer 3 modifier, not a new resolution layer -- Key design decision: economy mode ONLY affects Layer 3 auto-selection — Layer 0/1/2 (user intent) always wins -- `💰` indicator in spawn acknowledgments keeps it transparent -- Activation via session phrase, persistent config (`economyMode: true` in config.json), or CLI flag -- Architecture trips shift from opus → sonnet; code tasks shift from sonnet → gpt-4.1/gpt-5-mini -- Confidence: `low` — first implementation, not yet validated - -**Personal squad governance (proposals):** -- Gap analysis: coordinator has no consult mode awareness despite full SDK implementation -- Five gaps identified: Init Mode missing personal squad resolution, no consult mode detection, TEAM_ROOT has no personal-squad semantics, charter templates lack consult-mode patterns, no consult-mode skill -- Proposed `CONSULT_MODE: true` as spawn prompt signal, `🧳 consult` in acknowledgments -- Proposed new consult-mode skill (after governance approval — skill after governance, not before) - -**Governance workflow pattern:** When proposals touch squad.agent.md (governance territory), write to `decisions/inbox/` for Flight review. Don't directly edit squad.agent.md — Flight reviews governance changes. - -**Catalog audit finding:** `claude-sonnet-4.6`, `gpt-5.4`, `gpt-5.3-codex` appear in model-selection SKILL.md fallback chains but are absent from squad.agent.md's "Valid models" catalog. Documented in economy-mode governance proposal for Flight to address. - -### Session 2 Summary (2026-03-22) - -Wave 1 governance work on #500 and #344: authored economy-mode skill (`SKILL.md`), economy-mode governance proposal, and personal-squad governance proposal. Caught `claude-sonnet-4.6` missing from valid models catalog. PR #503 (`squad/500-344-governance`) merged to dev. - -### 2025-07: Spawn template `name` parameter fix (#577) - -**Problem:** Agent cast names weren't displayed during work — the tasks panel showed generic slugs like "general-purpose-task" instead of the cast name. Root cause: spawn templates in `squad.agent.md` specified `description` but NOT the `name` parameter for the `task` tool. The `name` parameter generates the human-readable agent ID shown in the tasks panel. - -**Fix:** Added `name: "{name}"` (lowercase cast name) to all spawn templates in `.squad-templates/squad.agent.md`: -- Lightweight Spawn Template -- Model-passing example -- Main full spawn template ("Template for any agent") - Scribe spawn template (hardcoded `name: "scribe"`) Also updated: examples section (showing `name` + `description` pairs), anti-pattern #4 (now covers both `name` and `description`), and Constraints section (requiring `name` on every spawn). @@ -228,4 +117,3 @@ Also updated: examples section (showing `name` + `description` pairs), anti-patt **Files modified:** `.github/copilot-instructions.md`, `.copilot/skills/protected-files/SKILL.md` (new). **Pattern:** When trimming agent instructions, extract domain-specific reference content to skills (lazy-loaded on demand) and keep the main instructions file as a routing/workflow document. Skills are the right abstraction for "read this when you touch X" — they don't consume tokens until needed. - diff --git a/.squad/decisions.md b/.squad/decisions.md index 9ed383264..91fd48fa3 100644 --- a/.squad/decisions.md +++ b/.squad/decisions.md @@ -1,64 +1,112 @@ -# Decisions - -> Team decisions that all agents must respect. Managed by Scribe. - - ---- - -## Foundational Directives (carried from beta, updated for Mission Control) - -### Type safety — strict mode non-negotiable -**By:** CONTROL (formerly Edie) -**What:** `strict: true`, `noUncheckedIndexedAccess: true`, no `@ts-ignore` allowed. -**Why:** Types are contracts. If it compiles, it works. - -### Hook-based governance over prompt instructions -**By:** RETRO (formerly Baer) -**What:** Security, PII, and file-write guards are implemented via the hooks module, NOT prompt instructions. -**Why:** Prompts can be ignored. Hooks are code — they execute deterministically. - -### Node.js >=20, ESM-only, streaming-first -**By:** GNC (formerly Fortier) -**What:** Runtime target is Node.js 20+. ESM-only. Async iterators over buffers. -**Why:** Modern Node.js features enable cleaner async patterns. - -### Casting — Apollo 13, mission identity -**By:** Squad Coordinator -**What:** Team names drawn from Apollo 13 / NASA Mission Control. Scribe is always Scribe. Ralph is always Ralph. Previous universe (The Usual Suspects) retired to alumni. -**Why:** The team outgrew its original universe. Apollo 13 captures collaborative pressure, technical precision, and mission-critical coordination — perfect for an AI agent framework. - -### Proposal-first workflow -**By:** Flight (formerly Keaton) -**What:** Meaningful changes require a proposal in `docs/proposals/` before execution. -**Why:** Proposals create alignment before code is written. - -### Tone ceiling — always enforced -**By:** PAO (formerly McManus) -**What:** No hype, no hand-waving, no claims without citations. -**Why:** Trust is earned through accuracy, not enthusiasm. - -### Zero-dependency scaffolding preserved -**By:** Network (formerly Rabin) -**What:** CLI remains thin. Zero runtime dependencies for the CLI scaffolding path. -**Why:** Users should be able to run `npx` without downloading a dependency tree. - -### Merge driver for append-only files -**By:** Squad Coordinator -**What:** `.gitattributes` uses `merge=union` for `.squad/decisions.md`, `agents/*/history.md`, `log/**`, `orchestration-log/**`. -**Why:** Enables conflict-free merging of team state across branches. - -### Interactive Shell as Primary UX -**By:** Brady -**What:** Squad becomes its own interactive CLI shell. `squad` with no args enters a REPL. -**Why:** Squad needs to own the full interactive experience. - +# Decisions + +> Team decisions that all agents must respect. Managed by Scribe. + + +--- + +### 2026-08-19: Squad's responsibility matrix stops at this repo +**Date:** 2026-08-19 +**Raised by:** bradygaster (via Copilot session) +**Status:** Decided + +## Context + +During follow-up planning after a live end-to-end Squad test, the coordinator +repeatedly proposed opening a pull request against `github/gh-aw` to refresh +that repo's copy of `workflows/squad.md`, on the theory that stale content +there was blocking `github/gh-aw#53498`. + +Brady rejected this three times. The proposal came from misreading the +`source: bradygaster/squad/workflows/squad.md@dev` line in gh-aw's copy as +evidence of a vendoring relationship that obligated us to keep their copy +current. + +## Decision + +**All Squad work happens in `bradygaster/squad`.** We do not push code or +changes to `gh-aw` or any other external repository. The only work that +happens outside this repo is running tests in targeted test repos. + +The gh-aw copy of `squad.md` is where some of their experimentation happens. +It is not ours to maintain, and no work item should be opened against it +until further notice. + +## Relationship framing (corrected) + +Squad and gh-aw are **not** vendors of each other's code in either direction. + +- `workflows/squad.md` originated inside gh-aw and was **moved here**. This + repo is where that file and its siblings live now. +- We depend on gh-aw only to do "Squad things using gh-aw" — it is a runtime + we build on, not a downstream consumer we ship to. +- A `source:` pin appearing in another repo is their provenance metadata. It + does not create an obligation on us. + +## Consequences + +- No follow-up item may be framed as "refresh / upstream / sync to gh-aw." +- Findings that appear to be gh-aw defects are theirs to triage. We may still + investigate one to understand our own behavior, but investigation does not + imply we open anything there. +- Test repos (e.g. `bradygaster/aspiregregator-squad-test`) remain in scope + for verification work. + +## Foundational Directives (carried from beta, updated for Mission Control) + +### Type safety — strict mode non-negotiable +**By:** CONTROL (formerly Edie) +**What:** `strict: true`, `noUncheckedIndexedAccess: true`, no `@ts-ignore` allowed. +**Why:** Types are contracts. If it compiles, it works. + +### Hook-based governance over prompt instructions +**By:** RETRO (formerly Baer) +**What:** Security, PII, and file-write guards are implemented via the hooks module, NOT prompt instructions. +**Why:** Prompts can be ignored. Hooks are code — they execute deterministically. + +### Node.js >=20, ESM-only, streaming-first +**By:** GNC (formerly Fortier) +**What:** Runtime target is Node.js 20+. ESM-only. Async iterators over buffers. +**Why:** Modern Node.js features enable cleaner async patterns. + +### Casting — Apollo 13, mission identity +**By:** Squad Coordinator +**What:** Team names drawn from Apollo 13 / NASA Mission Control. Scribe is always Scribe. Ralph is always Ralph. Previous universe (The Usual Suspects) retired to alumni. +**Why:** The team outgrew its original universe. Apollo 13 captures collaborative pressure, technical precision, and mission-critical coordination — perfect for an AI agent framework. + +### Proposal-first workflow +**By:** Flight (formerly Keaton) +**What:** Meaningful changes require a proposal in `docs/proposals/` before execution. +**Why:** Proposals create alignment before code is written. + +### Tone ceiling — always enforced +**By:** PAO (formerly McManus) +**What:** No hype, no hand-waving, no claims without citations. +**Why:** Trust is earned through accuracy, not enthusiasm. + +### Zero-dependency scaffolding preserved +**By:** Network (formerly Rabin) +**What:** CLI remains thin. Zero runtime dependencies for the CLI scaffolding path. +**Why:** Users should be able to run `npx` without downloading a dependency tree. + +### Merge driver for append-only files +**By:** Squad Coordinator +**What:** `.gitattributes` uses `merge=union` for `.squad/decisions.md`, `agents/*/history.md`, `log/**`, `orchestration-log/**`. +**Why:** Enables conflict-free merging of team state across branches. + +### Interactive Shell as Primary UX +**By:** Brady +**What:** Squad becomes its own interactive CLI shell. `squad` with no args enters a REPL. +**Why:** Squad needs to own the full interactive experience. + ### Root Cause Analysis Three factors combine to create the VS Code routing failure. Ranked by dominance: #### 1. 🔴 CLI-Centric Enforcement Language (DOMINANT) -The routing constraint is expressed exclusively in CLI terms. The CRITICAL RULE references ask tool only. When the coordinator reads this in VS Code, where the tool is unSubagent, it doesn't reliably make the substitution. It falls through to Platform Detection's Fallback mode: 'work inline.' This enforcement language creates a logical gap. +The routing constraint is expressed exclusively in CLI terms. The CRITICAL RULE references ask tool only. When the coordinator reads this in VS Code, where the tool is +unSubagent, it doesn't reliably make the substitution. It falls through to Platform Detection's Fallback mode: 'work inline.' This enforcement language creates a logical gap. #### 2. 🟡 Prompt Saturation (AMPLIFYING) @@ -72,7 +120,8 @@ CLI 1.0.11 discovers all \*.agent.md\ files from cwd to git root. Squad has 5 co **Fix 1: Platform-Neutral Enforcement Language (P0)** - Rewrite CRITICAL RULE to be platform-neutral: 'You are a DISPATCHER, not a DOER. Every task that needs domain expertise MUST be dispatched to a specialist agent.' -- List dispatch mechanisms: CLI (\ ask\ tool), VS Code (\ unSubagent\ tool), or fallback (work inline) +- List dispatch mechanisms: CLI (\ ask\ tool), VS Code (\ +unSubagent\ tool), or fallback (work inline) - Update anti-patterns and constraints sections with same substitution **Fix 2: Top-and-Bottom Reinforcement (P0)** @@ -90,7 +139,8 @@ CLI 1.0.11 discovers all \*.agent.md\ files from cwd to git root. Squad has 5 co **Fix 5: VS Code-Specific Hardening Block (P1)** - Move VS Code adaptations section higher (from line 458 to immediately after CRITICAL RULE) - Restructure as active enforcement block with platform detection table -- Make clear: if \ unSubagent\ is available, it MUST be used for domain work +- Make clear: if \ +unSubagent\ is available, it MUST be used for domain work ### Priority Ordering @@ -109,7 +159,8 @@ CLI 1.0.11 discovers all \*.agent.md\ files from cwd to git root. Squad has 5 co After implementing, test with Andreas's reproduction case: 1. Open VS Code with squadified project 2. Ask coordinator to do domain work that matches routing rule -3. Verify: coordinator dispatches via \ unSubagent\ instead of working inline +3. Verify: coordinator dispatches via \ +unSubagent\ instead of working inline 4. Verify: coordinator cites the routing rule when dispatching FIDO should own the test scenario. GUIDO should validate the VS Code runtime behavior. @@ -118,7 +169,8 @@ FIDO should own the test scenario. GUIDO should validate the VS Code runtime beh 1. Does CLI 1.0.11 support exclusion patterns (.copilotignore)? If yes, Fix 4 becomes simpler. 2. Should we version-gate the VS Code adaptations (detect CLI version)? -3. Is \ unSubagent\ still the correct tool name, or has it changed? +3. Is \ +unSubagent\ still the correct tool name, or has it changed? --- # Decision: PR Review Batch — Overlap Resolution @@ -235,135 +287,617 @@ 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 - ---- - -### 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. +## 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 +### 2026-07-29: Workflow templates linted via explicit actionlint file paths **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. +**What:** Templates under `packages/squad-cli/templates/workflows/` and `packages/squad-sdk/templates/workflows/` are now linted by actionlint via explicit file path arguments in the new `squad-workflow-lint.yml` CI job. SC2086 findings fixed across all `>> $GITHUB_OUTPUT` / `>> $GITHUB_STEP_SUMMARY` redirects in `.squad-templates/workflows/`, `templates/workflows/`, `.github/workflows/squad-heartbeat.yml`, `squad-repo-health.yml`, and `squad-ci.yml`. Actionlint pinned to tag `v1.7.12`; shellcheck 0.10.0 installed explicitly. +**Why:** Downstream repos running actionlint in their CI saw SC2086 errors in files generated by `squad upgrade` because Squad's own CI did not lint templates. The fix must live in Squad's templates — `squad upgrade` overwrites any downstream patches on every run. PR #1557. +## 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: Copilot git safety rules +### 2026-08-19: Finding D: slash_command plus bots concurrency warning +**Date:** 2026-08-19T13:30:18.326-07:00 +**By:** Booster +**Area:** Squad workflow trigger/concurrency behavior -**By:** RETRO (Security) -**What:** Added mandatory Git Safety section to copilot-instructions.md: prohibits broad repo-root staging commands, 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. +## Finding ---- +Compiling `workflows/squad.md` with `gh aw compile workflows\squad.md --no-emit --no-check-update` reproduces the warning: -### 2026-03-29: Versioning policy — no prerelease versions on dev/main +```text +workflows\squad.md: warning: Both slash_command and bots triggers are configured. If a bot listed in bots: posts a comment that starts with the slash command text (e.g., /command-name), it will trigger the workflow and occupy the concurrency slot, potentially blocking simultaneous manual invocations. To ensure the workflow only runs on explicit user commands, remove the 'bots:' field. +``` -**By:** Flight (Lead) -**What:** (1) All packages use strict semver (MAJOR.MINOR.PATCH) — no prerelease suffixes on dev or main. (2) Prerelease versions (`-build.N`) are local-only, never committed. (3) SDK and CLI versions must stay in sync. (4) Surgeon owns version bumps. (5) CI gate `prerelease-version-guard` blocks PRs with prerelease versions; `skip-version-check` label is Surgeon-only. -**Why:** PR #640 — prerelease `0.9.1-build.4` silently broke workspace resolution; PR #116 — Surgeon set wrong prerelease version on release branch. No documented policy caused both incidents. Full policy in `.squad/skills/versioning-policy/SKILL.md`. +The compile also fails afterward because the local worktree does not have the referenced `squad-implement-worker` in the compiler's expected `.github\workflows` directory, but the warning is emitted before that unrelated failure. ---- +gh-aw emits the warning in `pkg/workflow/compiler_validators.go` from `emitGeneralToolWarnings` when both `len(workflowData.Command) > 0` and `len(workflowData.Bots) > 0`. -### 2026-04-25: Release process skill update — v0.9.4 learnings +## Mechanism -**By:** Booster (CI/CD) -**What:** Updated `.squad/skills/release-process/SKILL.md` and `.copilot/skills/release-process/SKILL.md` with v0.9.4 incident learnings: root package.json version drift (read by squad-release.yml, not sub-packages), CHANGELOG must include `## [$VERSION]` entry, lockfile integrity check must filter registry-only packages, GITHUB_TOKEN cannot trigger downstream workflows, prebuild bump breaks workspace linking. -**Why:** v0.9.4 release was delayed by three distinct issues (PRs #1042, #1043, #1044). Documenting prevents recurrence. +`workflows/squad.md` configures: ---- +```yaml +on: + bots: ["github-actions[bot]"] + slash_command: + name: squad +``` + +gh-aw command matching accepts comments that are exactly `/squad`, start with `/squad `, or start with `/squad\n`. For comment triggers, actors listed in `bots:` are exempted from the normal owner/member/collaborator author-association guard, so a `github-actions[bot]` comment beginning with `/squad` can pass activation. + +The workflow has no explicit concurrency block, so gh-aw auto-generates command/slash-command workflow concurrency keyed by workflow plus issue/PR number, with `cancel-in-progress` disabled for command workflows. A bot-authored `/squad ...` comment on the same issue therefore shares the same concurrency slot as a human `/squad ...` comment on that issue. + +GitHub Actions permits one running and one pending run per concurrency group by default. If the bot run is running, the human run is delayed as pending. If another run in the same group queues while the human run is pending, the older pending run can be canceled and replaced. The failure can be effectively silent from the issue thread; the signal is in Actions UI/logs, not necessarily a Squad comment. + +## Assessment + +This is a real but narrow hazard. Our current `bots:` entry is only `github-actions[bot]`. Our own gh-aw/Squad failure and status comments can be authored by that bot, but the observed `[aw]` failure-report class does not begin with `/squad`, so it does not match the slash-command predicate. + +For the e2e chain we care about — `/squad implement` → epic → child PR → merge → worker dispatches Squad continuation — this warning is unlikely to bite unless one of our bot-authored comments begins with `/squad`. The continuation hop uses `dispatch-workflow` / `workflow_dispatch` inputs, not a bot issue comment, so it does not require `bots:` and does not depend on bot-authored slash-command comments. + +## Options + +1. **Remove `bots:` from `workflows/squad.md`.** Clears the warning and prevents bot-authored `/squad` comments from occupying the human command slot. Cost: any intentional GitHub Actions bot slash-command automation stops working. I found no evidence the implement continuation needs that. +2. **Narrow `bots:`.** Already as narrow as possible for this use case (`github-actions[bot]` only). No practical improvement unless there is a more specific bot identity. +3. **Custom concurrency group with bot isolation.** Could route bot actors to `github.run_id`, but gh-aw still emits this warning because the check only looks at `slash_command` plus non-empty `bots`. It also preserves bot-triggered `/squad` execution, which is the behavior creating risk. +4. **Restructure triggers / split bot handling.** Viable only if we need bot slash-command support. More complexity than warranted for the e2e path. +5. **Suppress or ignore.** Leaves warning noise and a narrow real hazard. Acceptable for immediate e2e only if no bot comments start with `/squad`. + +## Recommendation + +Address it, but do not block the immediate e2e rerun on it. The clean product configuration is to remove `bots:` from `workflows/squad.md` unless Flight identifies a required bot-authored slash-command scenario. The continuation hop we are proving uses workflow dispatch, so removing `bots:` should not weaken that path. If the team wants zero churn before the e2e rerun, doing nothing is operationally acceptable as long as the rerun issue avoids bot comments beginning with `/squad`. + +### 2026-08-19: Finding F: protected-files request_review and signed commits +**Date:** 2026-08-19T13:11:34.130-07:00 +**By:** Booster +**Area:** gh-aw safe-output protection for Squad Implement Worker -### 2026-06-24: Restore always-on coordinator inline-dispatch gate +## Verdict + +The hard refusal is real signed-commit behavior, not a missing protected-files lookup. gh-aw first classifies `protected-files: request_review` as a soft protected-file action, but the signed-commit replay path revalidates the synthesized GraphQL payload and rejects every file-protection action except `allow`. + +That makes `request_review` effectively incompatible with signed `create-pull-request` writes that touch protected files. The user-visible soft-log/hard-fail sequence is an integration/documentation bug in gh-aw, but the signed path is deliberately fail-closed. + +## Mechanism + +1. `create_pull_request.cjs` calls `checkFileProtection(...)` with the configured policy defaulting to `request_review`. +2. For `request_review`, it logs that it will create the pull request with a caution and request-changes review. +3. The handler then calls `pushSignedCommits(...)` with the same validation config. +4. `push_signed_commits.cjs` synthesizes the GraphQL `createCommitOnBranch` file payload and calls `checkFileProtectionPostApply(...)`. +5. If the returned action is anything other than `allow`, it throws `Signed-commit payload violates file-protection policy (...)`. +6. `request_review` therefore soft-logs at PR-handler level, then hard-refuses at signed-push level. + +`fallback-to-issue` follows a different route: the same signed-push validation still rejects the protected payload, but the PR handler has `manifestProtectionFallback` set, catches the push failure, and creates the protected-file review issue instead of trying to create the PR. + +## Worker recommendation + +For `workflows/squad-implement-worker.md`, keep the existing `excluded-files` list for structural no-write zones: + +```yaml +excluded-files: + - ".github/workflows/**" + - "**/.github/workflows/**" + - ".github/agents/**" + - "**/.github/agents/**" + - ".github/aw/**" + - "**/.github/aw/**" + - ".squad/**" + - "**/.squad/**" +``` + +Change `protected-files: request_review` to: + +```yaml +protected-files: fallback-to-issue +``` + +Do not set `protected-files: allowed` unless the worker is intentionally allowed to rewrite protected manifests, security docs, and other top-level dot folders. `excluded-files` and `protected-files` overlap only for the excluded protected directories. `excluded-files` strips those paths from the patch before commit creation; `protected-files` still protects package manifests, lockfiles, `CODEOWNERS`, `README.md`, `SECURITY.md`, `CHANGELOG.md`, and other non-excluded protected files. + +## E2E rerun viability + +This should unblock the e2e rerun for the worker path. A protected-file write will no longer produce the misleading `request_review` soft path followed by a signed-payload hard failure; it will be routed to the protected-file review issue path. Writes under `.github/workflows/`, `.github/agents/`, `.github/aw/`, and `.squad/` should be stripped before protected-file evaluation because of `excluded-files`. + +Any workflow-source change must be recompiled into the installed `.lock.yml` used by `bradygaster/aspiregregator-squad-test`; editing this repo's Markdown source alone will not affect an already-compiled test workflow. + +## Risk + +The recommendation does not weaken the no-write zones covered by `excluded-files`; those files remain absent from the generated patch. It does change the protected-file outcome from failed/contradictory `request_review` to review-issue fallback. The worker does not gain ability to commit excluded directories, but it can still propose normal allowed source files. Protected non-excluded files will require manual review through an issue instead of being opened as a PR with requested changes. + +### 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) + +### New Knowledge Added + +| Issue | Root Cause | Fix PR | Skill Section | +|-------|-----------|--------|---------------| +| Root package.json version drift | squad-release.yml reads from root, not sub-packages | #1043 | Known Gotchas + v0.9.4 Incident Learnings | +| CHANGELOG missing `## [$VERSION]` | Workflow validates version entry exists | #1042 | Known Gotchas + Release Checklist | +| Lockfile integrity check rejects workspace packages | Check didn't filter for registry-only packages | #1044 | Known Gotchas + Common Failure Modes | +| GITHUB_TOKEN can't trigger downstream workflows | GitHub security feature prevents event propagation | N/A (design) | GITHUB_TOKEN section + Manual Publish | +| Prebuild bump breaks workspace linking | bump-build.mjs mutates versions breaking exact match | N/A (known) | Local Development section | + +### Cross-References +- Added bidirectional cross-references between team-level and copilot-level skill files +- Added PR references (#1042, #1043, #1044) as source evidence throughout + +## 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 the v0.9.4 delays. The GITHUB_TOKEN limitation in particular is non-obvious and would catch any future release. + +### 2026-08-08: `/squad plan` Workflow Design +**Date:** 2026-08-08 +**Raised by:** bradygaster (via Copilot session) +**Status:** Open +**Related:** `.squad/decisions/inbox/copilot-sdlc-workflows.md` + +## Context + +After casting (#8 → PR #9 on Aspiregregator), the natural next step is decomposing the issue into actionable sub-issues. Today this requires manual work. A `/squad plan` command would let the squad generate a plan from an issue, get approval, then create sub-issues. + +## UX Flow (Proposed) + +``` +User writes issue #8 (big feature/epic) + ↓ +/squad cast → PR with team (already works ✅) + ↓ +/squad plan → Squad reads issue, posts structured plan as comment + ↓ +User reviews plan comment + ↓ +/squad plan accept → Squad creates sub-issues from the plan +``` + +## UX Options for the Accept Step + +### Option A: `/squad plan accept` (recommended) + +``` +/squad plan → generates plan comment +/squad plan accept → creates sub-issues from last plan comment +/squad plan revise ... → revises plan based on feedback, posts new comment +``` + +- **Pro:** Explicit, discoverable, follows the existing `/squad ` pattern +- **Pro:** Feedback loop — user can `/squad plan revise "split the React work into 3 phases"` before accepting +- **Con:** User must type another comment to accept + +### Option B: Checkbox-based acceptance + +The plan comment includes GitHub task-list checkboxes: +```markdown +## Proposed Plan +- [x] Issue: Platform modernization (auto-checked = will be created) +- [x] Issue: Orleans architecture completion +- [ ] Issue: Security hardening (unchecked = skip) + +Reply `/squad plan accept` to create the checked items. +``` + +- **Pro:** User can selectively approve individual items before accepting +- **Con:** More complex — agent must re-read the edited comment and parse checkbox state +- **Con:** Editing someone else's comment (bot's) feels weird; user would need to quote/copy + +### Option C: Reaction-based acceptance (👍 on plan comment) + +- **Pro:** Zero typing — just react to accept +- **Con:** gh-aw likely can't trigger on reactions (not in the events list) +- **Con:** Too easy to accidentally accept + +### Option D: Draft PR as plan artifact + +`/squad plan` creates a draft PR containing a `PLAN.md` with the proposed issues in markdown. Merge = accept. + +- **Pro:** Native review workflow (comments, suggestions, approvals) +- **Con:** Plans aren't code — feels wrong to use a PR +- **Con:** Adds merge noise to the repo + +## Workflow Architecture Options + +### Option 1: Extend existing `squad.md` workflow (minimal) + +Add `plan`, `plan accept`, `plan revise` to the existing modes table. No new workflow needed. + +```yaml +# Just add to the Modes table: +| `/squad plan` | Plan | Decompose issue into sub-issues (proposes, doesn't create) | +| `/squad plan accept` | Plan Accept | Create sub-issues from last plan comment | +| `/squad plan revise` | Plan Revise | Revise plan based on feedback | +``` + +- **Pro:** Zero additional install — anyone with `/squad` already has planning +- **Pro:** Shares the same team context (squad state restored from activation) +- **Con:** `safe-outputs.create-issue.max: 5` is too low for planning decomposition +- **Con:** Workflow grows in complexity; permissions are shared across modes +- **Mitigation:** Bump `create-issue.max` to 20 + +### Option 2: Separate `workflows/plan.md` (composable) + +New top-level workflow: `/plan` slash command, imports `shared/squad.md` for team state. + +```yaml +name: Plan +on: + slash_command: + name: plan + events: [issues, issue_comment] +permissions: + contents: read + copilot-requests: write + issues: write # needs write to create sub-issues +safe-outputs: + create-issue: + labels: [squad, planned] + max: 20 + add-comment: + max: 10 +imports: + - shared/squad.md +``` + +- **Pro:** Dedicated permissions (issues: write only when planning) +- **Pro:** Clean separation — cast and plan are independent workflows +- **Pro:** Users opt-in to planning separately: `gh aw add bradygaster/squad/workflows/plan.md@dev` +- **Con:** Extra install step for users +- **Con:** `/plan` is a separate namespace from `/squad` (less discoverable) + +### Option 3: Hybrid — `shared/plan.md` component imported by `squad.md` + +```yaml +# In workflows/squad.md: +imports: + - shared/squad.md + - shared/plan.md +``` + +- **Pro:** Single install, single `/squad` namespace, but planning logic lives in its own shared component +- **Pro:** Others can also import `shared/plan.md` into their own workflows +- **Con:** Permissions must cover both casting and planning in one workflow + +## Recommendation + +**Option A (UX) + Option 3 (architecture)** — Keep `/squad plan` under the existing `/squad` namespace (discoverability), implement planning logic in `shared/plan.md` (composability), and bump `create-issue.max` to 20. + +The flow becomes: +1. `/squad plan` → reads issue body + repo context, generates structured plan comment with sub-issues, effort estimates, dependencies, and agent assignments +2. User reviews, optionally replies `/squad plan revise "merge items 3 and 4, add a migration step"` +3. `/squad plan accept` → creates sub-issues with labels, assignments, and dependency references + +Plan comments should be structured with: +- Numbered work items with titles and scope descriptions +- Dependency order (which items block which) +- Agent assignments (which squad member owns each item) +- Effort signals (S/M/L) +- A summary of what `/squad plan accept` will create + +## State Between Runs + +gh-aw runs are stateless. The plan comment IS the state: +- `/squad plan` → posts a comment with a specific marker (e.g., ``) +- `/squad plan accept` → searches issue comments for the latest plan marker, parses it, creates issues +- `/squad plan revise` → finds the latest plan, revises it, posts a new plan comment (supersedes the old one) + +## Open Questions + +1. Should `/squad plan accept` also assign the created issues to squad members (via labels like `squad:lead`)? +2. Should plan comments include task-list checkboxes for selective acceptance? +3. Should the plan reference the team from PR #9's `.squad/team.md`, or work without a cast team? +4. Max issues to create in one plan — 20? 30? + +## Decision + +*(Pending — to be resolved by the team)* + +### 2026-08-08: Should Squad ship pre-baked SDLC workflows? +**Date:** 2026-08-08 +**Raised by:** bradygaster (via Copilot session) +**Status:** Open + +## Context -**By:** Procedures (Prompt Engineer) -**What:** Re-established a strong always-on dispatch gate in `.squad-templates/squad.agent.md`, synced to all 5 copies: (1) inline-dispatch gate — inline only in Direct Mode or when neither `task` nor `runSubagent` exists; (2) STOP gate before emitting domain artifacts without a spawn call; (3) VS Code `runSubagent` micro-playbook re-inlined. Changeset added. Regression test `test/coordinator-inline-dispatch-gate.test.ts` (8/8 pass). -**Why:** Commit `afe78188` (#1035) moved the inline-dispatch gate to lazy-loaded reference files, causing the coordinator to execute domain work itself instead of dispatching. Reported by Matthew Wan; workaround by Dina Berry. +Squad currently owns team formation and coordination (`workflows/squad.md` + `shared/squad.md`). Once a squad is cast, the actual SDLC — plan, implement, test, review — happens through the agents but there's no pre-built gh-aw workflow for those phases. Users go from "I have a squad" to "now what?" with a gap. +The question: should Squad ship optional SDLC workflows (plan, implement, review), or leave that space to other tools/integrations? + +## Options + +### A — Squad stays team-only (status quo) + +- Squad owns casting, coordination, and routing +- SDLC workflows are the user's responsibility or come from third parties +- Other tools can `imports: - shared/squad.md` to compose Squad into their own pipelines +- **Pro:** Tight scope, easier to maintain, no opinions on how teams should work +- **Con:** Biggest friction point ("I cast a squad… now what?") remains unsolved + +### B — Ship optional SDLC workflows under `workflows/shared/` + +- Add composable shared components: `shared/plan.md`, `shared/implement.md`, `shared/review.md` +- Each imports `shared/squad.md` for team state +- Ship a top-level `workflows/sdlc.md` that composes all phases as a batteries-included option +- Users who only want casting still use `workflows/squad.md` alone +- **Pro:** Closes the adoption gap, composable (not mandatory), demonstrates the `shared/` pattern +- **Con:** More surface area to maintain, risk of being too opinionated + +### C — Ship a single "do work" workflow, not a full SDLC + +- One additional workflow (e.g., `workflows/work.md`) that takes an issue and delegates it to the squad +- Lighter than a full SDLC pipeline — just "give an issue to the squad and let them figure it out" +- **Pro:** Minimal scope increase, high value, lets the squad's routing/coordination handle the rest +- **Con:** Doesn't cover structured SDLC phases (planning, review gates) + +## Recommendation + +Option B with a phased rollout — start with a single `shared/implement.md` component (the highest-value gap), then add plan and review later based on usage. This keeps the composable `shared/` pattern intact while solving the immediate "now what?" problem. + +## Decision + +*(Pending — to be resolved by the team)* + +### 2026-08-19: restore shared ancestry between dev and main via merge, dev-wins conflict policy +--- +author: Data +date: 2026-08-13 +status: decided +references: + - "PR #1699" + - "PR #1698 (v0.12.0 dev -> main promotion, unblocked by this)" + - "PR #1415 (tools: ['*'] fix, verified already on dev)" --- -### 2026-07-29: Workflow templates linted via explicit actionlint file paths +# Decision: restore shared ancestry between dev and main via merge, dev-wins conflict policy -**By:** Booster (CI/CD) -**What:** Templates under `packages/squad-cli/templates/workflows/` and `packages/squad-sdk/templates/workflows/` are now linted by actionlint via explicit file path arguments in the new `squad-workflow-lint.yml` CI job. SC2086 findings fixed across all `>> $GITHUB_OUTPUT` / `>> $GITHUB_STEP_SUMMARY` redirects in `.squad-templates/workflows/`, `templates/workflows/`, `.github/workflows/squad-heartbeat.yml`, `squad-repo-health.yml`, and `squad-ci.yml`. Actionlint pinned to tag `v1.7.12`; shellcheck 0.10.0 installed explicitly. -**Why:** Downstream repos running actionlint in their CI saw SC2086 errors in files generated by `squad upgrade` because Squad's own CI did not lint templates. The fix must live in Squad's templates — `squad upgrade` overwrites any downstream patches on every run. PR #1557. -## Deferred +## Context -- #357, #336, #335, #334, #333, #332, #316 (A2A) — stays shelved per existing decision -- #581 (ADO PRD) — P2, blocked until #341 (SDK-first parity) ships +`dev` and `main` had unrelated git histories. `dev`'s root commit (`4c5772c5`, a +dependabot bump dated 2026-07-13) shares no ancestor with `main`'s root +(`f4830e48`, 1722 commits). `dev` itself has 196 commits. `git merge-base +upstream/dev upstream/main` returned nothing and `git merge-tree` refused +outright. This made the v0.12.0 promotion PR (#1698, `dev` -> `main`) flatly +unmergeable, with no way to review a normal diff. The v0.11.0 promotion +(2026-06-29) predates the July 13 reset, which is why it worked and why +#1698 was the first to hit this wall. + +## Decision + +Merge `upstream/main` into `dev` with `--allow-unrelated-histories`, resolving +every one of the 275 conflicts in `dev`'s favor, on a new branch +`squad/restore-main-ancestry`, landed via PR #1699 into `dev`. + +Rejected alternative: rebasing `dev` onto `main`. `dev` carries a +`non_fast_forward` ruleset that blocks the force-push a rebase requires, and a +rebase would rewrite all 196 commits on `dev`, invalidating every PR currently +open against it. A merge is additive only and needs no force-push. + +## Why dev-wins conflict resolution is safe + +All 275 conflicts were `add/add` (identical path on both branches, no common +base to 3-way merge from). Resolved every one with `git checkout --ours` (dev's +content). This is safe because the only `main`-only code fix that mattered, +#1415 (`tools: ['*']` in `.github/agents/squad.agent.md`), was verified already +present on `dev` before starting the merge, so dev-wins loses zero code. +Verified the resolution was a true no-op against dev's pre-merge tree: diffing +all 275 resolved files plus the 48 removed changesets plus the 6 auto-merged +files against dev's HEAD showed only 18 real changes total, exactly the +files deliberately kept (see below). Confirmed unchanged post-merge: +`package.json` / `packages/squad-cli/package.json` / `packages/squad-sdk/package.json` +(all `0.12.0`), `CHANGELOG.md` (`## [0.12.0] - 2026-08-12` intact), +`test/gh-aw-quality.test.ts` (#1697 fix intact), `workflows/squad.md` and +`workflows/squad-implement-worker.md` (#1682 feature intact). + +## What was restored (kept from main, lost in the July 13 reset) + +7 docs pages: +- docs/src/content/blog/015-wave-2-the-repl-moment.md +- docs/src/content/blog/032-v010-stabilisation-insider.md +- docs/src/content/blog/033-swe-bench-lite-results.md +- docs/src/content/docs/features/remote-control.md +- docs/src/content/docs/get-started/choosing-your-path.md +- docs/src/content/docs/guide/personal-squad.md +- docs/src/content/docs/guide/shell.md + +5 decision records: +- .squad/decisions/inbox/booster-ci-deletion-guard.md +- .squad/decisions/inbox/booster-release-skill-v094.md +- .squad/decisions/inbox/flight-versioning-policy.md +- .squad/decisions/inbox/procedures-fix-coordinator-inline-dispatch-gate.md +- .squad/decisions/inbox/retro-copilot-git-safety.md + +Plus 6 files that auto-merged cleanly via a genuine 3-way merge (not a +conflict), appending older history from main onto dev's existing content with +no loss on either side: `.squad/agents/{eecom,fido,flight,pao,procedures}/history.md` +and `.squad/decisions.md`. + +## What was dropped + +48 `.changeset/*.md` files that arrived from `main`. These are spent: their +content is already consumed into `CHANGELOG.md`'s `[0.12.0]` entry, and +re-adding them risked tripping the Changeset Drift check. `.changeset/` after +this merge contains exactly what `dev` had before: `README.md`, +`config.json`, `max-reasoning-effort.md`. + +## Validation + +Static/diff verification was thorough (see above). Dynamic validation +(`npm run build`, `npx vitest run`) could **not** be executed in this sandbox: +the corporate npm proxy does not mirror `eslint-plugin-n@18.3.0` (its cache +tops out at 18.2.2) and there is no direct route to the public npm registry +from this environment. Confirmed unrelated to the merge: +`package-lock.json`'s staged content is byte-identical to dev's pre-merge +HEAD, and this exact dependency/version was already in dev's lockfile before +any of this work. CI (which has full registry access) is the source of truth +for build/test validation on PR #1699. + +## Outcome + +`git merge-base upstream/main` now succeeds, confirming `dev` +has a real common ancestor with `main` again. This unblocks PR #1698 and +prevents the same failure on future promotions, provided the new release-process +skill gate (verify `git merge-base dev main` before starting release-prep) is +followed going forward. + +### 2026-07-27: 2026-07-27: Dispatch Enforcement — Stop Coordinator From Doing Domain Work Inline +**Status:** ACCEPTED (empirically validated in tamresearch1 worktree; ported to bradygaster/squad) +**Proposed by:** Picard, Data, Q (review chain) +**Validated by:** Ralph (E2E test report, 2026-07-27) +**PR:** See squad/dispatch-enforcement branch on tamirdresher_microsoft:squad-squad + +## Decision + +Squad coordinators MUST dispatch all domain work to specialist agents. Inline work by the coordinator is a contract violation. Three enforcement layers are being shipped: + +### Layer A — Coordinator Tool Profile Restriction + +Apply a `tools:` allowlist in the coordinator agent's frontmatter (`.github/agents/squad.agent.md`). The allowlist contains only dispatch-safe tools: + +```yaml +tools: + - agent + - read + - search + - skill + - squad_state/* + - squad_state_c3c25b85/* + - squad_state_e7f10a1f/* + - github-mcp-server/* +``` + +**Effect:** Physical prevention — the Copilot runtime blocks any tool call outside this list with a hard error (`Unknown tool name in the tool allowlist: "create"`). Empirically verified across all 3 Test 1 turns. + +**Meta-gap (accepted):** Because `create` and `edit` are blocked at the coordinator level, the DispatchGuard ledger (Layer B) cannot be written by the coordinator itself. Layer B becomes opt-in observation mode when Layer A is active. This is an accepted trade-off per Q Recommendation #6: unverifiable compliance ≠ free pass. + +### Layer B — Scribe DispatchGuard Mechanical Audit + +Scribe is spawned in DispatchGuard mode at every session start. It reads the coordinator's turn ledger (`.squad/orchestration-log/dispatchguard/ledger-{SESSION_ID}.jsonl`) and audits each turn via `.squad/hooks/dispatch-audit.ps1` / `.squad/hooks/dispatch-audit.sh`. Verdicts are appended to a verdicts file consumed by Ralph. + +**Enforcement mode:** `dispatchEnforcement: "warn"` (see `.squad/config.json`). Can be escalated to `"block"` to halt coordinator work on violation. + +**Infrastructure:** `.squad/hooks/dispatch-audit.ps1` (Windows/PowerShell 7+), `.squad/hooks/dispatch-audit.sh` (Linux/macOS, requires jq ≥ 1.6), test fixtures in `.squad/hooks/tests/`. + +### Layer C v2 — Dispatch Contract Wording + +The coordinator prompt (`squad.agent.md`) includes: +- An explicit **Direct-Mode whitelist** (5 exhaustive cases where inline work is permitted) +- The **Domain-Artifact rule** (everything not on the whitelist must dispatch) +- The **Narrow inbox exemption** (≤500-word `.squad/decisions/inbox/*.md` files only) +- **Verb triggers** (explicit list of verbs requiring dispatch when paired with domain-artifact objects) +- The **Read-Only Probe Budget** (max 2 reads before dispatch is required) +- The **Anti-pattern prohibition** (enumerated rationalizations that are explicitly NOT valid overrides) +- The **Session Init DispatchGuard Auto-Bootstrap** (mandatory Scribe spawn every session, first ack turn) +- The **Bootstrap Verification** (coordinator must confirm Scribe DispatchGuard is live before proceeding) + +## Empirical Evidence + +Tested in tamresearch1 worktree, 2026-07-27 (Ralph report `ralph-e2e-post-layer-a-report.md`): + +| Turn | Verb | Pre-Layer-C | Layer-C only | Layer-A+B+C | Result | +|------|------|-------------|--------------|-------------|--------| +| 1 | analyze | drift | drift | DISPATCHED | ✅ Fixed | +| 2 | propose | drift | drift | DISPATCHED | ✅ Fixed | +| 3 | apply | dispatched | drift REGRESSED | DISPATCHED | ✅ Regression reversed | + +Verbatim tool-block errors confirming Layer A enforcement: +``` +● Unknown tool name in the tool allowlist: "create" +● Unknown tool name in the tool allowlist: "edit" +● Unknown tool name in the tool allowlist: "grep" +``` + +## Known Limitations + +1. **Audit meta-gap** (HIGH): Layer A blocks `create`/`edit` → coordinator can't write DispatchGuard ledger → `dispatch-audit.ps1` always returns `indeterminate` for real sessions. Layer B and Layer A are mutually incompatible in Phase 1. Accepted trade-off. +2. **`grep` tool unintended casualty** (MED): `grep` is the CLI-native search tool, not in the allowlist. `read` and `search` are allowed. Scribe/sub-agents use `grep` from their own (unrestricted) tool context — not blocked. +3. **Coverage gap** (INFO): Layer A only applies when the coordinator is invoked via `agent` tool. External repos without squad routing labels don't trigger SquadShort/Squad coordinator → Layer A doesn't apply. +4. **Verbal override NOT supported**: `dispatchEnforcement: "off"` in `.squad/config.json` (committed diff) is the only valid override. Verbal in-turn overrides are NOT a supported path. + +## Override Path + +To disable enforcement: commit `dispatchEnforcement: "off"` in `.squad/config.json`. This is the ONLY valid override — a committed, reviewable diff, not a verbal in-session request. + +## Files Added/Modified + +- `.squad/config.json` — added `dispatchEnforcement: "warn"` +- `.squad/agents/scribe/charter.md` — added Tool Access section + DispatchGuard section +- `.squad/agents/ralph/charter.md` — replaced stub with full charter including Verdict Consumer + Skills +- `.squad/hooks/dispatch-audit.ps1` — 410-line PowerShell audit script +- `.squad/hooks/dispatch-audit.sh` — bash port (parity-verified) +- `.squad/hooks/README.md` — platform guide +- `.squad/hooks/tests/` — 7 JSONL fixtures + 2 parity test runners +- `.squad/templates/orchestration-log.md` — appended DispatchGuard ledger schema +- `.squad/routing.md` — extended Routing Principles with DispatchGuard notes +- `.github/copilot-instructions.md` — added identity lock + routing guard + adversarial input handling +- `.github/instructions/squad-routing-guard.instructions.md` — new file: explicit routing rules +- `.gitignore` — added `.squad/orchestration-log/dispatchguard/` +- `.github/agents/squad.agent.md` — Layer A frontmatter + Layer C v2 body prose + +### 2026-08-19: Squad protected-files policy +**Date:** 2026-08-19T13:11:34.130-07:00 +**By:** Flight +**Area:** Squad Implement Worker protected-file policy + +## Recommendation + +Choose **B**: + +```yaml +protected-files: + policy: fallback-to-issue + exclude: + - README.md +``` + +This should be Squad's shipped worker default for now. It fixes the `request_review`/signed-commit incompatibility without turning routine README work into a dead-end review issue. It keeps the genuinely load-bearing protected files protected: dependency manifests, lockfiles, `CODEOWNERS`, `SECURITY.md`, `CONTRIBUTING.md`, `CHANGELOG.md`, and top-level dot folders not already stripped by `excluded-files`. + +Do not choose plain `fallback-to-issue` as the product default. It is mechanically safe but creates the wrong default UX for a core Squad use case: docs improvement by PAO. Do not choose the broader docs exclusion yet. `README.md` is special because it is both high-frequency and low-control-plane. `CONTRIBUTING.md` and `CHANGELOG.md` can be process/release-control files in adopting repositories. + +## Threat model + +The protected-file guard is not primarily protecting `dev` from an unreviewed merge; the PR review gate already does that. It is protecting reviewers and repo owners from high-leverage changes being normalized into routine agent output. + +Protected status is load-bearing when a file can change: + +- the dependency graph or supply-chain surface (`package.json`, lockfiles, `go.mod`, `pyproject.toml`, `Gemfile`, `Directory.Packages.props`, etc.); +- install/build/test execution (`scripts`, package manager config, SDK/toolchain pinning); +- repository governance (`CODEOWNERS`, `SECURITY.md`, `CONTRIBUTING.md`); +- release provenance or release automation assumptions (`CHANGELOG.md` in many repos); +- future automation behavior through top-level dot folders, where not already removed by `excluded-files`. + +For those files, `fallback-to-issue` forces a human to explicitly acknowledge that the work is crossing a policy boundary before the patch becomes a normal PR. That extra friction is justified. + +`README.md` does not carry the same default threat. It can mislead users, but that risk is visible in ordinary review and is exactly the kind of work Squad should handle. Protecting every basename `README.md` at every depth is inherited from gh-aw's generic manifest-safety model, not from Squad's product model. + +## Unit of configuration + +Ship B as the worker default, then surface protected-file policy as an adopting-repo configuration choice in the connect/adopt path. + +The worker needs a safe, opinionated default because every adopter starts somewhere. But repo owners differ: regulated repos may want strict plain `fallback-to-issue`; docs-heavy repos may want additional exclusions; experimental repos may choose a looser profile. This belongs beside the finding E preflight for Actions PR permissions. Both are adoption-time repository capability/safety choices, so they should share one preflight/configuration surface rather than becoming scattered workflow footnotes. + +The default should not wait for that surface. The current `request_review` value is broken with signed create-pull-request writes. + +## User experience of fallback-to-issue + +`fallback-to-issue` is acceptable as a policy-boundary escape hatch, not as the normal happy path. + +For a legitimate manifest task such as "add the Serilog package," an issue instead of a PR is frustrating but defensible: adding a dependency is a supply-chain decision, and the repo owner should consciously turn that issue into a PR or configure a looser policy. That outcome must be documented clearly so users understand it is a safety handoff, not a failed worker. + +For README work, the same experience is bad product behavior. It blocks common successful work, creates coordinator churn, and trains users that Squad cannot do basic docs tasks. That is why README should be excluded from protected-file defaults. + +## CHANGELOG.md + +Do not exclude `CHANGELOG.md` in the shipped default. + +This repo uses changesets, so Squad should normally write `.changeset/*.md`, not `CHANGELOG.md`. Adopting repos may not. In many projects `CHANGELOG.md` is release provenance, may be generated, and may be validated by release automation. A false changelog entry can be materially worse than a README edit because it can misstate shipped behavior or satisfy a release gate. Repos that intentionally maintain changelogs by hand can opt out later through the adoption configuration surface. + +## Follow-up +When implementation happens, update the workflow source and recompile the installed `.lock.yml` in any consuming/test repo used for validation. Keep the existing `excluded-files` rules; they solve a different problem and remain independent of this decision. diff --git a/.squad/decisions/inbox/booster-ci-deletion-guard.md b/.squad/decisions/inbox/booster-ci-deletion-guard.md deleted file mode 100644 index 581b1f419..000000000 --- a/.squad/decisions/inbox/booster-ci-deletion-guard.md +++ /dev/null @@ -1,4 +0,0 @@ -### 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. diff --git a/.squad/decisions/inbox/booster-release-skill-v094.md b/.squad/decisions/inbox/booster-release-skill-v094.md deleted file mode 100644 index b6858ce11..000000000 --- a/.squad/decisions/inbox/booster-release-skill-v094.md +++ /dev/null @@ -1,35 +0,0 @@ -# Decision: Release Process Skill Update — v0.9.4 Learnings - -**Author:** Booster (CI/CD Engineer) -**Date:** 2026-04-25 -**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. - -## Changes Made - -### 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) - -### New Knowledge Added - -| Issue | Root Cause | Fix PR | Skill Section | -|-------|-----------|--------|---------------| -| Root package.json version drift | squad-release.yml reads from root, not sub-packages | #1043 | Known Gotchas + v0.9.4 Incident Learnings | -| CHANGELOG missing `## [$VERSION]` | Workflow validates version entry exists | #1042 | Known Gotchas + Release Checklist | -| Lockfile integrity check rejects workspace packages | Check didn't filter for registry-only packages | #1044 | Known Gotchas + Common Failure Modes | -| GITHUB_TOKEN can't trigger downstream workflows | GitHub security feature prevents event propagation | N/A (design) | GITHUB_TOKEN section + Manual Publish | -| Prebuild bump breaks workspace linking | bump-build.mjs mutates versions breaking exact match | N/A (known) | Local Development section | - -### Cross-References -- Added bidirectional cross-references between team-level and copilot-level skill files -- Added PR references (#1042, #1043, #1044) as source evidence throughout - -## 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 the v0.9.4 delays. The GITHUB_TOKEN limitation in particular is non-obvious and would catch any future release. diff --git a/.squad/decisions/inbox/copilot-plan-workflow-ux.md b/.squad/decisions/inbox/copilot-plan-workflow-ux.md deleted file mode 100644 index 089cd3b7b..000000000 --- a/.squad/decisions/inbox/copilot-plan-workflow-ux.md +++ /dev/null @@ -1,164 +0,0 @@ -# Decision: `/squad plan` Workflow Design - -**Date:** 2026-08-08 -**Raised by:** bradygaster (via Copilot session) -**Status:** Open -**Related:** `.squad/decisions/inbox/copilot-sdlc-workflows.md` - -## Context - -After casting (#8 → PR #9 on Aspiregregator), the natural next step is decomposing the issue into actionable sub-issues. Today this requires manual work. A `/squad plan` command would let the squad generate a plan from an issue, get approval, then create sub-issues. - -## UX Flow (Proposed) - -``` -User writes issue #8 (big feature/epic) - ↓ -/squad cast → PR with team (already works ✅) - ↓ -/squad plan → Squad reads issue, posts structured plan as comment - ↓ -User reviews plan comment - ↓ -/squad plan accept → Squad creates sub-issues from the plan -``` - -## UX Options for the Accept Step - -### Option A: `/squad plan accept` (recommended) - -``` -/squad plan → generates plan comment -/squad plan accept → creates sub-issues from last plan comment -/squad plan revise ... → revises plan based on feedback, posts new comment -``` - -- **Pro:** Explicit, discoverable, follows the existing `/squad ` pattern -- **Pro:** Feedback loop — user can `/squad plan revise "split the React work into 3 phases"` before accepting -- **Con:** User must type another comment to accept - -### Option B: Checkbox-based acceptance - -The plan comment includes GitHub task-list checkboxes: -```markdown -## Proposed Plan -- [x] Issue: Platform modernization (auto-checked = will be created) -- [x] Issue: Orleans architecture completion -- [ ] Issue: Security hardening (unchecked = skip) - -Reply `/squad plan accept` to create the checked items. -``` - -- **Pro:** User can selectively approve individual items before accepting -- **Con:** More complex — agent must re-read the edited comment and parse checkbox state -- **Con:** Editing someone else's comment (bot's) feels weird; user would need to quote/copy - -### Option C: Reaction-based acceptance (👍 on plan comment) - -- **Pro:** Zero typing — just react to accept -- **Con:** gh-aw likely can't trigger on reactions (not in the events list) -- **Con:** Too easy to accidentally accept - -### Option D: Draft PR as plan artifact - -`/squad plan` creates a draft PR containing a `PLAN.md` with the proposed issues in markdown. Merge = accept. - -- **Pro:** Native review workflow (comments, suggestions, approvals) -- **Con:** Plans aren't code — feels wrong to use a PR -- **Con:** Adds merge noise to the repo - -## Workflow Architecture Options - -### Option 1: Extend existing `squad.md` workflow (minimal) - -Add `plan`, `plan accept`, `plan revise` to the existing modes table. No new workflow needed. - -```yaml -# Just add to the Modes table: -| `/squad plan` | Plan | Decompose issue into sub-issues (proposes, doesn't create) | -| `/squad plan accept` | Plan Accept | Create sub-issues from last plan comment | -| `/squad plan revise` | Plan Revise | Revise plan based on feedback | -``` - -- **Pro:** Zero additional install — anyone with `/squad` already has planning -- **Pro:** Shares the same team context (squad state restored from activation) -- **Con:** `safe-outputs.create-issue.max: 5` is too low for planning decomposition -- **Con:** Workflow grows in complexity; permissions are shared across modes -- **Mitigation:** Bump `create-issue.max` to 20 - -### Option 2: Separate `workflows/plan.md` (composable) - -New top-level workflow: `/plan` slash command, imports `shared/squad.md` for team state. - -```yaml -name: Plan -on: - slash_command: - name: plan - events: [issues, issue_comment] -permissions: - contents: read - copilot-requests: write - issues: write # needs write to create sub-issues -safe-outputs: - create-issue: - labels: [squad, planned] - max: 20 - add-comment: - max: 10 -imports: - - shared/squad.md -``` - -- **Pro:** Dedicated permissions (issues: write only when planning) -- **Pro:** Clean separation — cast and plan are independent workflows -- **Pro:** Users opt-in to planning separately: `gh aw add bradygaster/squad/workflows/plan.md@dev` -- **Con:** Extra install step for users -- **Con:** `/plan` is a separate namespace from `/squad` (less discoverable) - -### Option 3: Hybrid — `shared/plan.md` component imported by `squad.md` - -```yaml -# In workflows/squad.md: -imports: - - shared/squad.md - - shared/plan.md -``` - -- **Pro:** Single install, single `/squad` namespace, but planning logic lives in its own shared component -- **Pro:** Others can also import `shared/plan.md` into their own workflows -- **Con:** Permissions must cover both casting and planning in one workflow - -## Recommendation - -**Option A (UX) + Option 3 (architecture)** — Keep `/squad plan` under the existing `/squad` namespace (discoverability), implement planning logic in `shared/plan.md` (composability), and bump `create-issue.max` to 20. - -The flow becomes: -1. `/squad plan` → reads issue body + repo context, generates structured plan comment with sub-issues, effort estimates, dependencies, and agent assignments -2. User reviews, optionally replies `/squad plan revise "merge items 3 and 4, add a migration step"` -3. `/squad plan accept` → creates sub-issues with labels, assignments, and dependency references - -Plan comments should be structured with: -- Numbered work items with titles and scope descriptions -- Dependency order (which items block which) -- Agent assignments (which squad member owns each item) -- Effort signals (S/M/L) -- A summary of what `/squad plan accept` will create - -## State Between Runs - -gh-aw runs are stateless. The plan comment IS the state: -- `/squad plan` → posts a comment with a specific marker (e.g., ``) -- `/squad plan accept` → searches issue comments for the latest plan marker, parses it, creates issues -- `/squad plan revise` → finds the latest plan, revises it, posts a new plan comment (supersedes the old one) - -## Open Questions - -1. Should `/squad plan accept` also assign the created issues to squad members (via labels like `squad:lead`)? -2. Should plan comments include task-list checkboxes for selective acceptance? -3. Should the plan reference the team from PR #9's `.squad/team.md`, or work without a cast team? -4. Max issues to create in one plan — 20? 30? - -## Decision - -*(Pending — to be resolved by the team)* diff --git a/.squad/decisions/inbox/copilot-sdlc-workflows.md b/.squad/decisions/inbox/copilot-sdlc-workflows.md deleted file mode 100644 index c6a112ef2..000000000 --- a/.squad/decisions/inbox/copilot-sdlc-workflows.md +++ /dev/null @@ -1,45 +0,0 @@ -# Decision: Should Squad ship pre-baked SDLC workflows? - -**Date:** 2026-08-08 -**Raised by:** bradygaster (via Copilot session) -**Status:** Open - -## Context - -Squad currently owns team formation and coordination (`workflows/squad.md` + `shared/squad.md`). Once a squad is cast, the actual SDLC — plan, implement, test, review — happens through the agents but there's no pre-built gh-aw workflow for those phases. Users go from "I have a squad" to "now what?" with a gap. - -The question: should Squad ship optional SDLC workflows (plan, implement, review), or leave that space to other tools/integrations? - -## Options - -### A — Squad stays team-only (status quo) - -- Squad owns casting, coordination, and routing -- SDLC workflows are the user's responsibility or come from third parties -- Other tools can `imports: - shared/squad.md` to compose Squad into their own pipelines -- **Pro:** Tight scope, easier to maintain, no opinions on how teams should work -- **Con:** Biggest friction point ("I cast a squad… now what?") remains unsolved - -### B — Ship optional SDLC workflows under `workflows/shared/` - -- Add composable shared components: `shared/plan.md`, `shared/implement.md`, `shared/review.md` -- Each imports `shared/squad.md` for team state -- Ship a top-level `workflows/sdlc.md` that composes all phases as a batteries-included option -- Users who only want casting still use `workflows/squad.md` alone -- **Pro:** Closes the adoption gap, composable (not mandatory), demonstrates the `shared/` pattern -- **Con:** More surface area to maintain, risk of being too opinionated - -### C — Ship a single "do work" workflow, not a full SDLC - -- One additional workflow (e.g., `workflows/work.md`) that takes an issue and delegates it to the squad -- Lighter than a full SDLC pipeline — just "give an issue to the squad and let them figure it out" -- **Pro:** Minimal scope increase, high value, lets the squad's routing/coordination handle the rest -- **Con:** Doesn't cover structured SDLC phases (planning, review gates) - -## Recommendation - -Option B with a phased rollout — start with a single `shared/implement.md` component (the highest-value gap), then add plan and review later based on usage. This keeps the composable `shared/` pattern intact while solving the immediate "now what?" problem. - -## Decision - -*(Pending — to be resolved by the team)* diff --git a/.squad/decisions/inbox/data-restore-dev-main-ancestry.md b/.squad/decisions/inbox/data-restore-dev-main-ancestry.md deleted file mode 100644 index 513d7120a..000000000 --- a/.squad/decisions/inbox/data-restore-dev-main-ancestry.md +++ /dev/null @@ -1,100 +0,0 @@ ---- -author: Data -date: 2026-08-13 -status: decided -references: - - "PR #1699" - - "PR #1698 (v0.12.0 dev -> main promotion, unblocked by this)" - - "PR #1415 (tools: ['*'] fix, verified already on dev)" ---- - -# Decision: restore shared ancestry between dev and main via merge, dev-wins conflict policy - -## Context - -`dev` and `main` had unrelated git histories. `dev`'s root commit (`4c5772c5`, a -dependabot bump dated 2026-07-13) shares no ancestor with `main`'s root -(`f4830e48`, 1722 commits). `dev` itself has 196 commits. `git merge-base -upstream/dev upstream/main` returned nothing and `git merge-tree` refused -outright. This made the v0.12.0 promotion PR (#1698, `dev` -> `main`) flatly -unmergeable, with no way to review a normal diff. The v0.11.0 promotion -(2026-06-29) predates the July 13 reset, which is why it worked and why -#1698 was the first to hit this wall. - -## Decision - -Merge `upstream/main` into `dev` with `--allow-unrelated-histories`, resolving -every one of the 275 conflicts in `dev`'s favor, on a new branch -`squad/restore-main-ancestry`, landed via PR #1699 into `dev`. - -Rejected alternative: rebasing `dev` onto `main`. `dev` carries a -`non_fast_forward` ruleset that blocks the force-push a rebase requires, and a -rebase would rewrite all 196 commits on `dev`, invalidating every PR currently -open against it. A merge is additive only and needs no force-push. - -## Why dev-wins conflict resolution is safe - -All 275 conflicts were `add/add` (identical path on both branches, no common -base to 3-way merge from). Resolved every one with `git checkout --ours` (dev's -content). This is safe because the only `main`-only code fix that mattered, -#1415 (`tools: ['*']` in `.github/agents/squad.agent.md`), was verified already -present on `dev` before starting the merge, so dev-wins loses zero code. -Verified the resolution was a true no-op against dev's pre-merge tree: diffing -all 275 resolved files plus the 48 removed changesets plus the 6 auto-merged -files against dev's HEAD showed only 18 real changes total, exactly the -files deliberately kept (see below). Confirmed unchanged post-merge: -`package.json` / `packages/squad-cli/package.json` / `packages/squad-sdk/package.json` -(all `0.12.0`), `CHANGELOG.md` (`## [0.12.0] - 2026-08-12` intact), -`test/gh-aw-quality.test.ts` (#1697 fix intact), `workflows/squad.md` and -`workflows/squad-implement-worker.md` (#1682 feature intact). - -## What was restored (kept from main, lost in the July 13 reset) - -7 docs pages: -- docs/src/content/blog/015-wave-2-the-repl-moment.md -- docs/src/content/blog/032-v010-stabilisation-insider.md -- docs/src/content/blog/033-swe-bench-lite-results.md -- docs/src/content/docs/features/remote-control.md -- docs/src/content/docs/get-started/choosing-your-path.md -- docs/src/content/docs/guide/personal-squad.md -- docs/src/content/docs/guide/shell.md - -5 decision records: -- .squad/decisions/inbox/booster-ci-deletion-guard.md -- .squad/decisions/inbox/booster-release-skill-v094.md -- .squad/decisions/inbox/flight-versioning-policy.md -- .squad/decisions/inbox/procedures-fix-coordinator-inline-dispatch-gate.md -- .squad/decisions/inbox/retro-copilot-git-safety.md - -Plus 6 files that auto-merged cleanly via a genuine 3-way merge (not a -conflict), appending older history from main onto dev's existing content with -no loss on either side: `.squad/agents/{eecom,fido,flight,pao,procedures}/history.md` -and `.squad/decisions.md`. - -## What was dropped - -48 `.changeset/*.md` files that arrived from `main`. These are spent: their -content is already consumed into `CHANGELOG.md`'s `[0.12.0]` entry, and -re-adding them risked tripping the Changeset Drift check. `.changeset/` after -this merge contains exactly what `dev` had before: `README.md`, -`config.json`, `max-reasoning-effort.md`. - -## Validation - -Static/diff verification was thorough (see above). Dynamic validation -(`npm run build`, `npx vitest run`) could **not** be executed in this sandbox: -the corporate npm proxy does not mirror `eslint-plugin-n@18.3.0` (its cache -tops out at 18.2.2) and there is no direct route to the public npm registry -from this environment. Confirmed unrelated to the merge: -`package-lock.json`'s staged content is byte-identical to dev's pre-merge -HEAD, and this exact dependency/version was already in dev's lockfile before -any of this work. CI (which has full registry access) is the source of truth -for build/test validation on PR #1699. - -## Outcome - -`git merge-base upstream/main` now succeeds, confirming `dev` -has a real common ancestor with `main` again. This unblocks PR #1698 and -prevents the same failure on future promotions, provided the new release-process -skill gate (verify `git merge-base dev main` before starting release-prep) is -followed going forward. diff --git a/.squad/decisions/inbox/dispatch-enforcement-decision.md b/.squad/decisions/inbox/dispatch-enforcement-decision.md deleted file mode 100644 index 5e445a001..000000000 --- a/.squad/decisions/inbox/dispatch-enforcement-decision.md +++ /dev/null @@ -1,94 +0,0 @@ -### 2026-07-27: Dispatch Enforcement — Stop Coordinator From Doing Domain Work Inline - -**Status:** ACCEPTED (empirically validated in tamresearch1 worktree; ported to bradygaster/squad) -**Proposed by:** Picard, Data, Q (review chain) -**Validated by:** Ralph (E2E test report, 2026-07-27) -**PR:** See squad/dispatch-enforcement branch on tamirdresher_microsoft:squad-squad - -## Decision - -Squad coordinators MUST dispatch all domain work to specialist agents. Inline work by the coordinator is a contract violation. Three enforcement layers are being shipped: - -### Layer A — Coordinator Tool Profile Restriction - -Apply a `tools:` allowlist in the coordinator agent's frontmatter (`.github/agents/squad.agent.md`). The allowlist contains only dispatch-safe tools: - -```yaml -tools: - - agent - - read - - search - - skill - - squad_state/* - - squad_state_c3c25b85/* - - squad_state_e7f10a1f/* - - github-mcp-server/* -``` - -**Effect:** Physical prevention — the Copilot runtime blocks any tool call outside this list with a hard error (`Unknown tool name in the tool allowlist: "create"`). Empirically verified across all 3 Test 1 turns. - -**Meta-gap (accepted):** Because `create` and `edit` are blocked at the coordinator level, the DispatchGuard ledger (Layer B) cannot be written by the coordinator itself. Layer B becomes opt-in observation mode when Layer A is active. This is an accepted trade-off per Q Recommendation #6: unverifiable compliance ≠ free pass. - -### Layer B — Scribe DispatchGuard Mechanical Audit - -Scribe is spawned in DispatchGuard mode at every session start. It reads the coordinator's turn ledger (`.squad/orchestration-log/dispatchguard/ledger-{SESSION_ID}.jsonl`) and audits each turn via `.squad/hooks/dispatch-audit.ps1` / `.squad/hooks/dispatch-audit.sh`. Verdicts are appended to a verdicts file consumed by Ralph. - -**Enforcement mode:** `dispatchEnforcement: "warn"` (see `.squad/config.json`). Can be escalated to `"block"` to halt coordinator work on violation. - -**Infrastructure:** `.squad/hooks/dispatch-audit.ps1` (Windows/PowerShell 7+), `.squad/hooks/dispatch-audit.sh` (Linux/macOS, requires jq ≥ 1.6), test fixtures in `.squad/hooks/tests/`. - -### Layer C v2 — Dispatch Contract Wording - -The coordinator prompt (`squad.agent.md`) includes: -- An explicit **Direct-Mode whitelist** (5 exhaustive cases where inline work is permitted) -- The **Domain-Artifact rule** (everything not on the whitelist must dispatch) -- The **Narrow inbox exemption** (≤500-word `.squad/decisions/inbox/*.md` files only) -- **Verb triggers** (explicit list of verbs requiring dispatch when paired with domain-artifact objects) -- The **Read-Only Probe Budget** (max 2 reads before dispatch is required) -- The **Anti-pattern prohibition** (enumerated rationalizations that are explicitly NOT valid overrides) -- The **Session Init DispatchGuard Auto-Bootstrap** (mandatory Scribe spawn every session, first ack turn) -- The **Bootstrap Verification** (coordinator must confirm Scribe DispatchGuard is live before proceeding) - -## Empirical Evidence - -Tested in tamresearch1 worktree, 2026-07-27 (Ralph report `ralph-e2e-post-layer-a-report.md`): - -| Turn | Verb | Pre-Layer-C | Layer-C only | Layer-A+B+C | Result | -|------|------|-------------|--------------|-------------|--------| -| 1 | analyze | drift | drift | DISPATCHED | ✅ Fixed | -| 2 | propose | drift | drift | DISPATCHED | ✅ Fixed | -| 3 | apply | dispatched | drift REGRESSED | DISPATCHED | ✅ Regression reversed | - -Verbatim tool-block errors confirming Layer A enforcement: -``` -● Unknown tool name in the tool allowlist: "create" -● Unknown tool name in the tool allowlist: "edit" -● Unknown tool name in the tool allowlist: "grep" -``` - -## Known Limitations - -1. **Audit meta-gap** (HIGH): Layer A blocks `create`/`edit` → coordinator can't write DispatchGuard ledger → `dispatch-audit.ps1` always returns `indeterminate` for real sessions. Layer B and Layer A are mutually incompatible in Phase 1. Accepted trade-off. -2. **`grep` tool unintended casualty** (MED): `grep` is the CLI-native search tool, not in the allowlist. `read` and `search` are allowed. Scribe/sub-agents use `grep` from their own (unrestricted) tool context — not blocked. -3. **Coverage gap** (INFO): Layer A only applies when the coordinator is invoked via `agent` tool. External repos without squad routing labels don't trigger SquadShort/Squad coordinator → Layer A doesn't apply. -4. **Verbal override NOT supported**: `dispatchEnforcement: "off"` in `.squad/config.json` (committed diff) is the only valid override. Verbal in-turn overrides are NOT a supported path. - -## Override Path - -To disable enforcement: commit `dispatchEnforcement: "off"` in `.squad/config.json`. This is the ONLY valid override — a committed, reviewable diff, not a verbal in-session request. - -## Files Added/Modified - -- `.squad/config.json` — added `dispatchEnforcement: "warn"` -- `.squad/agents/scribe/charter.md` — added Tool Access section + DispatchGuard section -- `.squad/agents/ralph/charter.md` — replaced stub with full charter including Verdict Consumer + Skills -- `.squad/hooks/dispatch-audit.ps1` — 410-line PowerShell audit script -- `.squad/hooks/dispatch-audit.sh` — bash port (parity-verified) -- `.squad/hooks/README.md` — platform guide -- `.squad/hooks/tests/` — 7 JSONL fixtures + 2 parity test runners -- `.squad/templates/orchestration-log.md` — appended DispatchGuard ledger schema -- `.squad/routing.md` — extended Routing Principles with DispatchGuard notes -- `.github/copilot-instructions.md` — added identity lock + routing guard + adversarial input handling -- `.github/instructions/squad-routing-guard.instructions.md` — new file: explicit routing rules -- `.gitignore` — added `.squad/orchestration-log/dispatchguard/` -- `.github/agents/squad.agent.md` — Layer A frontmatter + Layer C v2 body prose diff --git a/.squad/decisions/inbox/flight-versioning-policy.md b/.squad/decisions/inbox/flight-versioning-policy.md deleted file mode 100644 index 9911fc318..000000000 --- a/.squad/decisions/inbox/flight-versioning-policy.md +++ /dev/null @@ -1,32 +0,0 @@ -# Decision: Versioning Policy — No Prerelease Versions on dev/main - -**By:** Flight (Lead) -**Date:** 2026-03-29 -**Requested by:** Dina -**Status:** DECIDED -**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. This caused two incidents: - -- **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 instead of the local workspace link. Four PRs (#637–#640) patched symptoms before the root cause was found. -- **PR #116:** Surgeon set versions to `0.9.1-build.1` instead of `0.9.1` on a release branch because there was no guidance on what constitutes a clean release version. - -## Skill Reference - -Full policy documented in `.squad/skills/versioning-policy/SKILL.md`. - -## Impact - -- All agents must follow the versioning policy when touching `package.json` -- Surgeon charter should reference this skill for release procedures -- CI pipeline enforces the policy via automated gate diff --git a/.squad/decisions/inbox/procedures-fix-coordinator-inline-dispatch-gate.md b/.squad/decisions/inbox/procedures-fix-coordinator-inline-dispatch-gate.md deleted file mode 100644 index e65fee749..000000000 --- a/.squad/decisions/inbox/procedures-fix-coordinator-inline-dispatch-gate.md +++ /dev/null @@ -1,45 +0,0 @@ -# Decision: Restore always-on coordinator inline-dispatch gate (v0.10.0 regression) - -- **Author:** Procedures (Prompt Engineer) -- **Date:** 2026-06-24 -- **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. Dina Berry worked around it by hand-editing the coordinator charter. - -## Root cause - -Commit `afe78188` (#1035, "context overflow sentinel + coordinator size reduction") cut the coordinator template and moved the concrete inline-dispatch gate and dispatch mechanics out of the always-on prompt into lazy-loaded reference files (`client-compatibility-reference.md`, `spawn-reference.md`). The leftover inline guidance ("inline work is last-resort fallback only") was too soft to hold the line, so the coordinator began executing domain work itself. - -## Decision - -Re-establish a strong, **always-on** dispatch gate without breaking the legitimate Direct/Lightweight response modes or the size-reduction spirit. Three minimal edits (~14 lines) to the canonical template `.squad-templates/squad.agent.md`, propagated to all 5 synced copies via `npm run sync-templates`: - -1. **Inline-dispatch gate** (Client Compatibility): inline permitted ONLY in Direct Mode, or when NEITHER `task` NOR `runSubagent` exists; otherwise MUST dispatch. -2. **STOP gate** (How to Spawn an Agent): 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. - -## The 5 synced copies (canonical first) - -1. `.squad-templates/squad.agent.md` (canonical — edited here) -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 - -- New regression/parity test `test/coordinator-inline-dispatch-gate.test.ts` (deterministic, subprocess-free): RED before (8/8 fail), GREEN after (8/8 pass). -- Full `npm run test`: 18 failed files vs 31 baseline (fewer); all failures are pre-existing flaky subprocess/timeout e2e tests (3 of 4 "new vs baseline" pass in isolation; the 4th is `squad doctor` at 40x10 exiting null = timeout, unrelated to template content). No new deterministic failures. -- `npm run lint` (tsc noEmit both packages): clean. - -## Changeset - -Required. The `changelog-gate` regex governs `.squad-templates/`, `templates/`, and `packages/squad-(sdk|cli)/templates/` — not just `src/`. 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/decisions/inbox/retro-copilot-git-safety.md b/.squad/decisions/inbox/retro-copilot-git-safety.md deleted file mode 100644 index bb1ed5256..000000000 --- a/.squad/decisions/inbox/retro-copilot-git-safety.md +++ /dev/null @@ -1,4 +0,0 @@ -### 2026-03-26: Copilot git safety rules -**By:** RETRO (Security) -**What:** Added mandatory Git Safety section to copilot-instructions.md: prohibits staging the entire working tree with a bare-dot `git add` (i.e. `git add` followed by just `.`), 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. From de492e398d744a30b1805d1acbb6a6810d22b247 Mon Sep 17 00:00:00 2001 From: brady gaster Date: Thu, 20 Aug 2026 09:36:44 -0700 Subject: [PATCH 2/2] Fix decision history archives Closes #1754 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- ...y-archive-2026-08-19T13-11-34.130-07-00.md | 225 +++++++++++ ...y-archive-2026-08-19T13-11-34.130-07-00.md | 366 ++++++++++++++++++ .squad/agents/eecom/history.md | 2 +- ...y-archive-2026-08-19T13-11-34.130-07-00.md | 251 ++++++++++++ ...y-archive-2026-08-19T13-11-34.130-07-00.md | 209 ++++++++++ ...y-archive-2026-08-19T13-11-34.130-07-00.md | 315 +++++++++++++++ ...y-archive-2026-08-19T13-11-34.130-07-00.md | 231 +++++++++++ .squad/decisions.md | 34 +- 8 files changed, 1605 insertions(+), 28 deletions(-) create mode 100644 .squad/agents/booster/history-archive-2026-08-19T13-11-34.130-07-00.md create mode 100644 .squad/agents/eecom/history-archive-2026-08-19T13-11-34.130-07-00.md create mode 100644 .squad/agents/fido/history-archive-2026-08-19T13-11-34.130-07-00.md create mode 100644 .squad/agents/flight/history-archive-2026-08-19T13-11-34.130-07-00.md create mode 100644 .squad/agents/pao/history-archive-2026-08-19T13-11-34.130-07-00.md create mode 100644 .squad/agents/procedures/history-archive-2026-08-19T13-11-34.130-07-00.md diff --git a/.squad/agents/booster/history-archive-2026-08-19T13-11-34.130-07-00.md b/.squad/agents/booster/history-archive-2026-08-19T13-11-34.130-07-00.md new file mode 100644 index 000000000..c1561cb38 --- /dev/null +++ b/.squad/agents/booster/history-archive-2026-08-19T13-11-34.130-07-00.md @@ -0,0 +1,225 @@ +# BOOSTER + +> Booster Systems Engineer + +## Learnings + +### CI Workflow Audit & Preflight Patterns (2026-03-23 Release Incident) +**Context:** v0.9.0 shipped with broken dependency reference (`file:../squad-sdk` in CLI package.json). Required hotfix. Used incident as opportunity to audit entire CI/CD system. + +**Audit findings:** 15 total workflow files. 7 load-bearing (ci, publish, release, preview, promote, insider variants). 7 administrative (triage, assign, labels, heartbeat, docs, link-check). 1 ghost (publish-npm.yml, deleted but GitHub index cached). No duplication. Authorship: 65% Brady, 10% Copilot (v0.9.1 scramble), 25% team. + +**Key patterns identified:** +- Preflight gate (dependency scanning + semver validation) prevents dependency defects +- Implicit ordering risk: squad-release and squad-npm-publish both trigger on `release: published` with no explicit job dependency (works but fragile) +- Ghost workflow cleanup: GitHub's workflow index caches file names; deletion doesn't immediately invalidate; must wait 15+ minutes or manually refresh + +**Preflight job pattern:** Scans `packages/*/package.json` for: +1. `file:` references (breaks published packages) +2. Invalid semver versions (rejects malformed versions) +Runs before smoke-test and all publish operations. Zero-cost gate (JSON reads only). Clear error messages with remediation instructions. + +### CI Pipeline Status +149 test files, 3,931 tests passing, ~89s runtime. Only failure: aspire-integration.test.ts (needs Docker daemon — pre-existing, expected). publish.yml triggers on `release: published` event with retry logic for npm registry propagation (5 attempts, 15s sleep). + +### Known CI Patterns +SKIP_BUILD_BUMP=1 environment variable intended to prevent version mutation during CI builds. Currently unreliable — bump-build.mjs ignores it in some code paths. NPM_TOKEN must be Automation type (not user token with 2FA) to avoid EOTP errors in publish workflow. + +### Workflow Inventory +9 load-bearing workflows (215 min/month) must stay as GitHub Actions. 5 migration candidates (12 min/month) could move to CLI: sync-labels, triage, assign, heartbeat, validate-labels. + +### Container Smoke Test Patterns +`npm pack` generates tarballs installable in clean containers for pre-publish validation. GitHub Actions containers (node:20-slim, node:22) suitable for smoke tests. No devcontainer config exists yet. Current CI budget: ~227 min/month. Container smoke test adds ~2-5 min per run. Tier 1 smoke test commands: `--version`, `--help`, `doctor`, `status`, `export`. CLI has 31 commands; 15 are user-facing smoke test candidates. cli-command-wiring.test.ts catches unwired commands at build time (issues #224, #236, #237). + +### Smoke Test Gating in Publish Pipeline +Smoke tests now run as a dedicated `smoke-test` job in publish.yml before any npm publish operations. Both publish-sdk and publish-cli jobs depend on smoke-test passing. Prevents publishing broken CLI packages to npm. Smoke test runs `npx vitest run test/cli-packaging-smoke.test.ts` after a full build. Test takes ~30-60s for pack+install validation. + +### CI Pipeline Hardening — March 20, 2026 + +**Changes shipped in commit 6cbabb5 (dev branch):** + +1. **`edited` trigger added** — `pull_request` event types now include `edited`. Previously, retargeting a PR from `main→dev` would not refire CI because the base branch change uses the `edited` event type. Six PRs (#470, #469, #468, #467, #454, #451) were manually close/reopened to compensate. + +2. **Lockfile lint step added** — New step `Lint lockfile for stale workspace entries` runs before `npm ci` in the `test` job. Uses Node inline script to detect any `packages/*/node_modules/@bradygaster/squad-*` entries in `package-lock.json` that have an `https://` resolved URL (indicating a stale nested registry copy shadowing the workspace symlink). Exits with error code + remediation instructions if found. This catches the TypeScript type-mismatch class of failures at the lockfile level, not at build time. + +3. **Default branch changed to `dev`** — Repo default branch switched from `main` to `dev` via GitHub API. Community PRs now naturally target `dev`. + +**Pattern confirmed:** The `edited` event gap was the exact reason retargeted PRs were not getting CI runs. Any future PR base-branch change will now trigger a fresh CI run automatically. + +### CI Failure Pattern Analysis — March 15, 2026 +Analyzed 20 CI runs from March 15. Identified 3 distinct failure categories: + +**1. TypeScript Build Failures — SDK/CLI Type Mismatches (Most Critical)** +- 7+ consecutive failures on `squad/fix-ci-build` branch (14:00-14:11 UTC) +- Root cause: Stale nested SDK entry in package-lock.json causing TypeScript module resolution errors +- Error: "Module '@bradygaster/squad-sdk' has no exported member 'listRoles'" (and 6 other missing exports) +- Impact: Build failures blocked all PRs attempting to fix roles/cast features +- Fix: Removing stale lockfile entry resolved TypeScript resolution +- Pattern: Workspace dependency mismatches not caught until CI build phase + +**2. Documentation Quality Gate Failures — New Validation Rules** +- 3 failures on `squad/docs-quality-ci` branch (14:32, 15:26, 15:51 UTC) +- Issue 1: Broken anchor link `../guide.md#troubleshooting` (anchor doesn't exist) +- Issue 2: Spell check failure for username "benleane" in notifications.md (not in cspell dictionary) +- Impact: New docs-quality job blocked merges when introducing new validation gates +- Pattern: Adding stricter CI gates without pre-validation of existing content creates immediate failures + +**3. Test Failures — ES Module Migration Side Effects (Legacy)** +- 1 failure on main branch (13:59 UTC) — "deleted images" commit +- Root cause: 8 test files using `require()` in ES module context +- Error: "require is not defined in ES module scope" (node:test imports) +- Impact: Old test files incompatible with `"type": "module"` in package.json +- Pattern: Incomplete ESM migration left test files in CommonJS syntax + +**Key Observations:** +- **Failure clusters**: Multiple consecutive failures trying to fix same root issue (TypeScript build: 7 attempts, docs-quality: 3 attempts) +- **Validation timing**: New validation gates (docs-quality CI) introduced without pre-testing against current codebase state +- **Workspace complexity**: Monorepo TypeScript workspace dependencies prone to lockfile staleness +- **Branch health**: dev branch had 2 failures (last failure: spell check), currently yellow/orange status + +**Recommended CI Improvements:** +1. Pre-merge lockfile validation check (detect stale nested dependencies) +2. Docs validation dry-run before adding new quality gates +3. TypeScript workspace reference health check (catch SDK/CLI type mismatches early) +4. Better failure grouping/attribution in CI UI (distinguish "new gate" vs "regression") +5. Spell check dictionary maintenance workflow (easier to add known-good usernames/terms) + +### CI Workflow Audit — March 23, 2026 + +**Status:** Conducted full audit of 15 workflow files. Brady's perception ("complete nightmare, 12,000 workflows") is not accurate — the codebase is lean, well-organized, and 99% authored by Brady (bradygaster + Copilot). + +**Key Findings:** +- **Total workflows:** 15 (7 load-bearing core, 7 admin/automation, 1 ghost) +- **Authorship:** bradygaster 46 commits (65%), Copilot 7 (10%), team 17 (24%) +- **v0.9.1 Scramble:** Copilot made 4 commits on 2026-03-23 trying to work around GitHub platform bug (workflow_dispatch returns 422 after file renames/deletes) +- **Ghost file identified:** `publish-npm.yml` (deleted but still in GitHub's workflow cache) → requires manual deletion via API +- **Zero duplication:** Each workflow has clear, non-overlapping responsibility +- **One optional cleanup:** `ci-rerun.yml` (useful but not essential) + +**Release Pipeline Quality:** +- Core pipeline (squad-ci → squad-release → squad-npm-publish → insider-*) is solid +- Smoke tests run before any npm publish (good safety gate) +- Implicit ordering works but fragile (squad-npm-publish depends on release: published event) + +**Triage Automation Quality:** +- Label routing (squad-triage, squad-issue-assign, squad-label-enforce) well-integrated +- Ralph heartbeat has cron disabled (event-driven only) +- Works correctly with @copilot assignment + +**Recommendation:** Delete ghost publish-npm.yml file, optionally keep ci-rerun for fork PR debugging, keep everything else. CI health is good. + +**Report written to:** `.squad/decisions/inbox/booster-ci-audit.md` + +### CI Cleanup & Hardening — Post-Audit + +**Changes shipped:** + +1. **Ghost workflow disabled** — `publish-npm.yml` (workflow ID 250121956) disabled via GitHub API (`PUT /actions/workflows/{id}/disable`). GitHub doesn't support DELETE on workflow entries; disable is the permanent fix. + +2. **Pre-publish `preflight` job added** to `squad-npm-publish.yml`: + - Scans ALL `packages/*/package.json` for `file:` references across all dependency sections (dependencies, devDependencies, optionalDependencies, peerDependencies) + - Validates all package versions are valid semver + - Runs BEFORE smoke-test and all publish jobs — blocks the entire pipeline if violations found + - This is the gate that would have caught the v0.9.1 incident + +3. **Smoke test enhanced** — Added `npm pack --dry-run` validation step for both SDK and CLI packages before the vitest smoke tests run + +4. **ci-rerun.yml retained** — Added purpose documentation comment. Still useful for fork PR re-testing and infrastructure flake recovery. + +5. **YAML fix** — Quoted `file:` in step names that were causing YAML parse ambiguity (both new and pre-existing) + +**Pipeline dependency chain:** `preflight → smoke-test → publish-sdk → publish-cli` + +### Release Process Skill Update — v0.9.4 Learnings (2026-04-25) + +Updated both release-process skill files (`.squad/skills/release-process/SKILL.md` and `.copilot/skills/release-process/SKILL.md`) with critical learnings from the v0.9.4 release session. Added 5 new Known Gotchas, a full `v0.9.4 Incident Learnings` section, GITHUB_TOKEN propagation workaround, CHANGELOG/root-package.json validation rules, lockfile integrity fix documentation, local dev recovery steps, and cross-references between skill files. Source PRs: #1042, #1043, #1044. + +### CI Cleanup — Issue #1000 (2026-04-17) + +**Changes shipped in PR #1001:** + +1. **Deleted `ci-rerun.yml`** — Redundant fork PR workflow with 100% failure rate (5/5 runs). GitHub's native "Approve and Run" handles fork PR CI. Removed reference from `setup-squad-node` comment header. + +2. **Streamlined `squad-ci.yml`** — 852 → 585 lines, 9 → 6 jobs: + - **Merged** `exports-map-check` + `export-smoke-test` → single `sdk-exports-validation` job (saves one runner boot, deduplicates checkout/setup/change-detection) + - **Folded** `publish-policy` + `scope-check` into `policy-gates` as additional gate steps (saves two runner boots) + - **Added** `workflows` output to `changes` path filter (policy-gates now properly skips on docs-only PRs) + - **Trimmed** verbose local-testing instruction comments and skip-labels reference block + - **Preserved** all genuine safety checks — no gates removed, only consolidated + +**Key decisions:** +- Merging exports-map-check + export-smoke-test is safe because they share identical prerequisites (SDK change detection, feature flags, skip labels) and both only need SDK build +- publish-policy (static grep of workflow files) fits naturally in policy-gates since it's a lightweight lint +- scope-check (label-gated) works inside policy-gates because the step has its own `if` condition for the `repo-health` label + +**Files modified:** +- `.github/workflows/ci-rerun.yml` (deleted) +- `.github/actions/setup-squad-node/action.yml` (comment update) +- `.github/workflows/squad-ci.yml` (streamlined) + +### Workflow Shellcheck SC2086 Fix + Actionlint CI Gate (2026-07-29T17:11:56+10:00) + +**Context:** Issue #1556 (bradygaster/squad) reported SC2086 failures in downstream repos using actionlint after `squad upgrade`. The unquoted `>> $GITHUB_OUTPUT` redirects in `squad-heartbeat.yml` were the reported trigger; audit revealed matching issues in `squad-repo-health.yml` and `squad-ci.yml` too. + +**Changes shipped:** + +1. **SC2086 fixes — all `>> $GITHUB_OUTPUT` and `>> $GITHUB_STEP_SUMMARY` redirects quoted** in: + - `.squad-templates/workflows/squad-heartbeat.yml` (canonical source, synced to 3 mirrors by build) + - `templates/workflows/squad-heartbeat.yml`, `packages/squad-cli/templates/workflows/squad-heartbeat.yml`, `packages/squad-sdk/templates/workflows/squad-heartbeat.yml` (mirrors) + - `.github/workflows/squad-heartbeat.yml` (active workflow, maintained separately per SYNC comment) + - `.github/workflows/squad-repo-health.yml` (4 run blocks, 10 lines total) + - `.github/workflows/squad-ci.yml` (1 large gate block, 13 lines total) + +2. **New CI workflow:** `.github/workflows/squad-workflow-lint.yml` + - Installs actionlint 1.7.12 + installs shellcheck 0.10.0 explicitly (ubuntu-latest ships 0.9.0) + - Lints `.github/workflows/*.yml` AND both template directories via explicit file paths + - Triggers on `pull_request` + `push` to dev/main with `paths:` filter + - Follows repo conventions: ubuntu-latest, `permissions: contents: read`, concurrency group + +3. **Changeset:** `.changeset/fix-workflow-shellcheck-quoting.md` — patch for squad-cli + squad-sdk (required because template files under `packages/squad-*/templates/` are covered by changelog-gate regex) + +**Key learnings:** +- The canonical workflow template source is `.squad-templates/workflows/` — fix templates THERE and the mirrors are auto-synced by `node scripts/sync-templates.mjs` during `prebuild` +- `.github/workflows/squad-heartbeat.yml` is maintained separately (SYNC comment at top of file) — must also be patched manually +- Template files can be linted by actionlint via explicit file paths — no need to copy them into `.github/workflows/` as a temp dir +- `npm run build` fails in this worktree environment due to missing TypeScript compiler (SSL install failure); the prebuild/sync phase succeeded and changes are correct YAML +- The `pull_request_target` context in `squad-repo-health.yml` uses only SHA values (not user-controlled text), so actionlint should NOT flag those as untrusted-input warnings + +**Part 2 deferred:** The `actions/checkout` v7→v4 clobbering on upgrade (the other regression in #1556) is out of scope for this PR and handled separately. + +### Actionlint CI Gate Gap Closure (2026-07-29T17:11:56+10:00 — follow-up) + +**Context:** Review identified two gaps in the squad-workflow-lint.yml shipped in the previous commit. + +**Gap 1 fixed:** `.squad-templates/workflows/` (canonical source, 11 files) and `templates/workflows/` (root mirror) were listed in `paths:` filters but had no corresponding lint steps. Added two new steps — "Lint canonical template source" and "Lint root mirror template workflows". Decision: lint all five directories from committed state (no sync step). Rationale: (a) bugs in canonical source are caught by the canonical lint step before sync propagates them; (b) mirror drift is already enforced by `template-sync.test.ts` as a separate gate. Sync-then-lint would test derived content, not what's committed. + +**Gap 2 fixed:** Installer script was fetched from `https://raw.githubusercontent.com/rhysd/actionlint/main/scripts/download-actionlint.bash` — a moving ref, unpinned RCE surface. Pinned to `v1.7.12` tag URL (verified: `raw.githubusercontent.com/rhysd/actionlint/v1.7.12/scripts/download-actionlint.bash` returns HTTP 200). + +**Shellcheck version:** ubuntu-latest ships shellcheck 0.9.0 (apt package `shellcheck 0.9.0-1`, confirmed in runner image README). Installed shellcheck 0.10.0 explicitly from GitHub releases (`shellcheck-v0.10.0.linux.x86_64.tar.xz`) to match the version cited in the original SC2086 reports. + +**Commit:** 1b1af6e3, pushed to `serbrech/squad`. + +### Installer Hardening — PR Review Comments (2026-07-29T19:25:08+10:00) + +**Context:** Copilot automated reviewer left 3 inline comments on PR #1557 (`squad-workflow-lint.yml` installer step + history.md). All valid and in scope. + +**Changes shipped:** + +1. **`bash <(curl -sL ...)` → download-then-run** (`squad-workflow-lint.yml` actionlint install): + - Replaced process substitution with `curl -fsSL ... > install-actionlint.bash && bash install-actionlint.bash && rm install-actionlint.bash` + - `-f` makes curl hard-fail on non-200 (e.g. 404 returns exit 22, not exit 0 with HTML body fed to bash) + - Named file is inspectable on failure; process substitution leaves no artifact + - `-s` (silent) retained via `-fsSL` to suppress progress noise while preserving all error signals + +2. **`set -euo pipefail` + `curl -fsSL` for shellcheck tar pipeline** (`squad-workflow-lint.yml`): + - Added `shell: bash` + `set -euo pipefail` at top of the install step + - GitHub Actions `run:` uses `bash -e` by default, NOT `-o pipefail`; curl failure in a `curl | tar` pipeline is masked by tar's exit status without it + - `-f` on shellcheck curl: same hard-fail-on-non-200 rationale + - Convention matched: `shell: bash` + `set -euo pipefail` inside run block, same as `squad-agents-ai-release.yml` (lines 76-78 and 135-139) and `squad-npm-publish.yml` (line 409) + +3. **History.md stale entry corrected** (line 174): + - Changed `Installs actionlint 1.7.12 + uses runner shellcheck` → `Installs actionlint 1.7.12 + installs shellcheck 0.10.0 explicitly (ubuntu-latest ships 0.9.0)` + - The old text was a stale artifact from the first iteration; lines 196-198 of this same file already documented the correct 0.10.0 explicit install + +**Validation:** `bash -n` passes on the new run block. Self-linting property holds — actionlint + shellcheck will lint this exact `run:` block on the next CI run, catching any quoting or syntax issues we introduce. Amended and force-pushed to `serbrech/squad` as a single commit. + diff --git a/.squad/agents/eecom/history-archive-2026-08-19T13-11-34.130-07-00.md b/.squad/agents/eecom/history-archive-2026-08-19T13-11-34.130-07-00.md new file mode 100644 index 000000000..9fb938d58 --- /dev/null +++ b/.squad/agents/eecom/history-archive-2026-08-19T13-11-34.130-07-00.md @@ -0,0 +1,366 @@ +# EECOM + +> Environmental, Electrical, and Consumables Manager + +## Core Context + +CLI entry point (`cli-entry.ts`) is the central router for 30+ commands. `safeTimestamp()` utility provides Windows-safe filenames (colons → hyphens). CastingEngine augments LLM casting with curated names — augment, not replace. `npm pack` produces complete installable tarball (~275KB). ESM module patch required for Node 24+ strict mode (@github/copilot-sdk@0.1.32 missing .js extension). + +## Recent Learnings + +### Template Brady contamination fix (#977) (2026-05-01) +Replaced all hardcoded "Brady" in template examples with generic `{user}`/`{name}` placeholders. Canonical sources: `.squad-templates/squad.agent.md` and `.copilot/skills/init-mode/SKILL.md`. Template sync only covers `.squad-templates/`; init-mode SKILL.md package copies required manual edits. Key distinction: only files copied to user repos were changed; Brady references in project docs are legitimate content. + +### PR #942 rebase — cherry-pick from insider-based fork branch (2026-04-12) +When cherry-picking from an insider-based branch to dev, expect modify/delete conflicts for files that only exist on insider. Always verify the base assumptions of each change — imports referencing insider-only modules must be dropped or adapted. Opened #963 as clean replacement, closed #942. + +### archiveDecisions() count-based fallback (#626) (2025-07-24) +Added count-based fallback when all `###` entries are <30 days old but file is >20KB. Separates recent entries into dated vs undated, sorts dated by age, keeps entries under threshold budget. **Rule:** Undated entries are always preserved (foundational directives). When a function has an early-return optimization, always consider whether the condition that triggered it can still be true when the early-return fires. + +### node:sqlite Hard-Fail Fix (#502) (2026-03-21) +Replaced soft-warn with synchronous version check + `process.exit(1)` for Node <22.5.0. Added `checkNodeVersion()` to `squad doctor`. Corrected `engines.node` to `>=22.5.0` in all package.json files. **Pattern:** Always confirm `git branch` before editing files — edits don't follow you to a new branch. + +### Personal Squad Init via npx (#576) (2026-03-23) +`init --global` now calls `ensurePersonalSquadDir()` after global init. Added idempotent `ensurePersonalSquadDir()` to SDK resolution.ts. `resolveGlobalSquadPath()` returns the container; `ensurePersonalSquadDir()` creates the `personal-squad/` subdirectory the rest of the system looks for. + +## Historical Learnings Summary (condensed) + +- **Loop command (#767):** For interactive/long-running child processes, always attach `.on('data')` listeners for real-time output. When using `node:fs` mocked in tests, use `vi.importActual('node:fs')` in `beforeAll` to get real filesystem access. teamRoot must derive from `detectSquadDir().path` not `workTreeRoot` in worktree scenarios. +- **Init scaffolding (no-remote, casting files) (#579):** Three execFileSync calls for git remote needed `stdio: ['pipe','pipe','pipe']` to suppress stderr. Init flow creates .squad/casting/ but never populated it — added scaffolding block. Pattern: execFileSync inside try/catch still leaks stderr without piped stdio. +- **CLI Version Subcommand:** `cmd === 'version'` added to existing `--version`/`-v` condition in cli-entry.ts. No separate command file needed for trivial inline handlers. +- **Privacy scrub messaging + EPERM + gitignore parent coverage (#549):** `ensureGitattributes` catches EPERM/EACCES, returns [] with console.warn. `ensureGitignore` skips entries with parent already covered. Footer shows "Privacy scrub applied" vs "Preserves user state" based on whether scrub ran. +- **Economy Mode (#500):** Layer 3 modifier only — never downgrades Layers 0-2 (user intent). `ECONOMY_MODEL_MAP` + `applyEconomyMode()` + CLI `squad economy on|off` + `--economy` flag. 34 tests. +- **Rate Limit UX (#464):** `rateLimitGuidance()` + `.squad/rate-limit-status.json` + `checkRateLimitStatus()` in doctor. Import `RateLimitError` from `@bradygaster/squad-sdk/adapter/errors` (subpath export, not main barrel). +- **CastingEngine CLI Integration (#342):** CastingEngine.castTeam() was never called in CLI flow. `augmentWithCastingEngine()` in cast.ts replaces LLM names with engine characters for recognized universes. Import from `@bradygaster/squad-sdk/casting` (not main barrel). 9 AgentRole enum values, not 6. +- **Cross-platform filename & config fixes (#348, #356):** Use centralized `safeTimestamp()` everywhere. Removed machine-specific `teamRoot` from config.json (computed at runtime via `git rev-parse`). +- **PR #427 cross-fork rebase:** When rebasing with git worktrees, always create a dedicated worktree for complex operations. In rebase context, "ours" = upstream, "theirs" = your branch. Use `git worktree list` to diagnose unexpected branch switching. +- **SDK Init Flow Deep Dive:** Critical gap: squad.config.ts never updated after auto-cast. CastingEngine exists but is never called. Roadmap: sync utility → Ralph fixes → CastingEngine integration → hire/remove commands. +- **Adoption Tracking Tier 1:** Moved `.squad/adoption/` → `.github/adoption/`. Aggregate metrics only — never publish individual repo lists without opt-in. +- **PR #483 (platform-adapter timeout):** `{ ...EXEC_OPTS, timeout: 3_000 }` pattern for external CLI calls that might hang. Existing catch block with fallback handles timeout errors. +- **PR #480 (history race condition):** Three-layer defense: async mutex, atomic file operations (write-then-rename), 14 tests. +- **PR #486 (SIGINT handling):** Two layers: parent SIGINT handler + child process cleanup (kill children, close handles, flush buffers). 22 tests. +## Learnings + +### Template Brady contamination fix (#977) (2026-05-01) + +**Context:** Template files (squad.agent.md, init-mode/SKILL.md) contained hardcoded "Brady" examples in greetings, routing examples, and comments. LLMs treated these as patterns, greeting every user as "Brady" regardless of their actual `git config user.name`. + +**Fix:** Replaced all hardcoded "Brady" in template examples with generic `{user}` / `{name}` placeholders. Canonical sources: `.squad-templates/squad.agent.md` and `.copilot/skills/init-mode/SKILL.md`. Template sync (`node scripts/sync-templates.mjs`) propagated squad.agent.md to `.github/agents/` but did NOT sync init-mode SKILL.md to package templates — those required manual edits in both `packages/squad-cli/templates/skills/init-mode/SKILL.md` and `packages/squad-sdk/templates/skills/init-mode/SKILL.md`. + +**Key distinction:** Only template files that get copied to user repos were changed. Brady references in project docs (history-hygiene, release-process, humanizer, architectural-proposals, reskill) are legitimate content about the project founder and were left unchanged. + +**Pattern:** When fixing template contamination, verify which files are covered by `sync-templates.mjs` and which require manual propagation. The init-mode SKILL.md lives in `.copilot/skills/` (not `.squad-templates/`), so sync doesn't touch its package copies. + +### PR #942 rebase — cherry-pick from insider-based fork branch (2026-04-12) + +**Context:** PR #942 from tamirdresher's fork was retargeted from `insider` to `dev`, causing 29 files in the diff when only 3 commits (4 files relevant to dev) were the actual fix. Cherry-picked the 3 fix commits onto a clean `squad/942-rebase-type-safety` branch from dev, resolving conflicts where insider-only files (skill.ts, cross-package-exports.test.ts) didn't exist on dev. Dropped the `escapeYamlValue` import and APM YAML generation function from init.ts since skill.ts doesn't exist on dev. Opened #963 as the clean replacement, closed #942. + +**Key lesson:** When cherry-picking from an insider-based branch to dev, expect modify/delete conflicts for files that only exist on insider. Always verify the base assumptions of each change — imports referencing insider-only modules must be dropped or adapted. + +### Loop command: second-round review fixes (#767) (2025-07-26) + +**Context:** Three Copilot review comments on PR #767: (1) `teamRoot` was set to `workTreeRoot` but `.squad/` may live in the main checkout when running inside a git worktree — should derive from `detectSquadDir().path`, (2) `generateLoopFile()` hardcoded the full loop.md scaffold inline, duplicating `templates/loop.md`, (3) docs said `gh` was optional but code hard-requires `gh copilot` unless `--agent-cmd` is passed. + +**Fixes:** +1. **teamRoot:** Changed `const teamRoot = workTreeRoot` to `path.dirname(squadDirInfo.path)` — `.squad/`-relative operations now always use the directory where `.squad/` was actually found. +2. **Template dedup:** Replaced 48-line hardcoded template with `readFileSync` reading from `templates/loop.md`. Used `import.meta.url` + `fileURLToPath` to resolve the path from the compiled file (3 levels up to package root). Created `packages/squad-cli/templates/loop.md` since it was missing from the CLI package's templates dir. +3. **Docs:** Updated prerequisites to state `gh` + `gh copilot` are required by default, with `--agent-cmd` as the escape hatch. + +**Test impact:** Tests mock `node:fs` globally, so `readFileSync` in `generateLoopFile()` needed mock setup. Added `beforeAll` using `vi.importActual('node:fs')` to read the REAL template file, then `beforeEach` to set the mock return value. This keeps tests validating the actual template content. + +**Pattern:** When reading template files in code that has mocked `node:fs` tests, use `vi.importActual('node:fs')` in `beforeAll` to get real filesystem access for loading test fixtures. + +### Loop command: streaming output, worktree CWD, docs alignment (#767) (2025-07-25) + +**Context:** Copilot code review on PR #767 flagged three issues in the loop command: (1) `execFile` buffered stdout/stderr but never printed it — users saw no Copilot output during loop rounds, (2) `loop.md` was resolved relative to `dest` but execution used `teamRoot` (derived from `.squad/` parent), creating a CWD mismatch in worktree scenarios, (3) docs said `description` defaults to `""` but code uses `'Squad Loop'`. + +**Fixes:** +1. **Streaming:** Added `.on('data')` listeners to `currentChild.stdout` and `currentChild.stderr` after `execFile` spawn. Since output streams in real-time, the callback no longer re-writes buffered stdout/stderr on error (would duplicate). +2. **Worktree CWD:** Introduced `workTreeRoot = path.resolve(dest)` and set `teamRoot = workTreeRoot`. Both file resolution and execution CWD now use the same root. +3. **Docs:** Updated `docs/src/content/docs/features/loop.md` description default from `""` to `"Squad Loop"`. + +**Key file:** `packages/squad-cli/src/cli/commands/loop.ts` — `runLoop()` entry point (~line 302), `executeRound()` inner function (~line 427). + +**Pattern:** When using Node's `execFile` for interactive/long-running child processes, always attach stream listeners for real-time output. The callback's `stdout`/`stderr` args are the same buffered content — writing both duplicates output. + +### archiveDecisions() count-based fallback (#626) (2025-07-24) + +**Context:** `archiveDecisions()` in `packages/squad-cli/src/cli/core/nap.ts` silently returned `null` when all `###` entries were <30 days old (`old.length === 0`), even if the file was well over 20KB. Active projects generating many decisions per session could hit 145KB+ — 35K tokens burned per agent spawn. + +**Fix:** Added a count-based fallback after the age-based split. When `old.length === 0` and total file size exceeds `DECISION_THRESHOLD` (20KB), the fallback separates recent entries into dated vs undated, sorts dated by age (most recent first), keeps entries that fit under the threshold budget, and archives the rest. Undated entries are always preserved — they are foundational directives per Procedures' guidance. + +**Key design choices:** +1. Undated entries (`daysAgo === null`) are never archived by the count-based fallback. They stay in `recent`. +2. Budget calculation accounts for header + undated entries + kept dated entries to guarantee the result fits under 20KB. +3. Entries are re-sorted into original document order after the split, so the output file preserves heading sequence. + +**Tests:** Added 4 adversarial tests — 50 all-today entries >20KB, mixed dated/undated preservation, under-threshold no-op, exact-threshold boundary case. + +**Pattern:** When a function has an early-return optimization (`if (old.length === 0) return null`), always consider whether the condition that triggered the function call (file size > threshold) can still be true when the early-return fires. If so, the early-return is a silent failure. + +### Init scaffolding: casting dir + no-remote stderr (#579) (2025-07-18) + +**Context:** `squad init` in a fresh `git init` repo (no remote) printed `error: No such remote 'origin'` to stderr and `squad doctor` reported `casting/registry.json` missing. Two independent bugs in `packages/squad-sdk/src/config/init.ts`. + +**Fix 1 — Stderr leak:** Three `execFileSync('git', ['remote', 'get-url', 'origin'])` calls in `initSquad()` were missing `stdio: ['pipe','pipe','pipe']`. The try/catch caught the error but git's stderr still leaked to the console. Added stdio piping to all three call sites (lines ~713, ~732, ~1039). + +**Fix 2 — Missing casting files:** The init flow created the `.squad/casting/` directory but never populated it. Added a scaffolding block after directory creation that copies `casting-policy.json`, `casting-registry.json`, and `casting-history.json` from SDK templates (with inline fallbacks). Respects `skipExisting` — never overwrites user files. + +**Pattern:** When calling `execFileSync` for a git command inside a try/catch, always add `stdio: ['pipe','pipe','pipe']` to suppress stderr. The catch prevents a crash, but without piped stdio the error message still prints to the user's terminal. + +### CLI Version Subcommand Pattern (2026-03-23 Release Incident) +**Context:** `squad version` returned "Unknown command: version" even though `squad --version` and `squad -v` worked fine. Classic "unwired command" bug but for a flag-to-subcommand gap rather than a missing import. + +**Pattern:** When a CLI flag works (`--foo`) but the equivalent subcommand doesn't (`foo`), the fix is almost always a single condition addition in `cli-entry.ts`. No separate command file needed for trivial handlers — inline alongside the flag handler. Added `cmd === 'version'` to the existing `--version`/`-v` condition. Also added `version` to help text command list. + +**Why inline works:** Trivial handlers that just print a value don't warrant their own module. Same output, same code path — no reason to split. Avoids adding a file the wiring test would require an import for. Precedent: `help` is also handled inline. + +### `squad version` subcommand (2026-07-15) + +**Context:** Running `squad version` returned "Unknown command: version" because the subcommand was never routed in `cli-entry.ts`, even though `--version` and `-v` flags worked fine. Classic "unwired command" bug class, but for a flag-to-subcommand gap rather than a missing import. + +**Fix:** Added `cmd === 'version'` to the existing `--version`/`-v` condition in `cli-entry.ts` (line ~130). Also added `version` to the help text command list. No new file in `cli/commands/` needed — this is a trivial inline handler, same as `--version`. The wiring test is unaffected since there's no separate command file. + +**Pattern:** When a CLI flag (`--foo`) works but the equivalent subcommand (`foo`) doesn't, the fix is almost always a single condition addition in `cli-entry.ts`. No separate command file needed for trivial handlers. + +### Privacy scrub messaging + EPERM + gitignore parent coverage (#549) (2026-07-14) + +**Context:** Upgrade footer message always said "Preserves user state" even when the email privacy scrub had run — a direct contradiction of what just happened. Two related issues in the same function: EPERM on read-only `.gitattributes` would crash the upgrade, and `.gitignore` would add redundant entries already covered by parent paths (e.g. `.squad/log/` when `.squad/` was already present). + +**Fix:** +1. `upgrade.ts` — `ensureGitattributes` catches EPERM/EACCES and returns `[]` with a console.warn, graceful degradation. +2. `upgrade.ts` — `ensureGitignore` skips an entry when any existing line is a parent prefix of it. +3. `upgrade.ts` — Footer logic checks whether the email scrub actually ran; shows "Privacy scrub applied" or "Preserves user state" accordingly. +4. `test/cli/upgrade.test.ts` — Added EPERM test using `chmodSync` (fix: `chmodSync` was missing from the `fs` import — added it). + +**Pattern:** When adding a new fs function to a test, always verify the named import list at the top of the test file. Missing named imports from `'fs'` produce `ReferenceError` at runtime, not at type-check time (if the test file isn't part of the main tsconfig). + +📌 **Team update (2026-03-22T09-35Z — Wave 1):** Economy mode fully implemented: ECONOMY_MODEL_MAP + resolveModel() integration in SDK, `squad economy on|off` CLI command, `--economy` flag, 34 tests passing. PR #504 open for review. Soft dependency: #464 rate limit UX should offer economy mode as recovery. Next: Phase 1 of ambient personal squad (T1–T5, T19) — ready to start immediately after merging current work. Procedures wrote governance proposals for squad.agent.md — awaiting Flight review. +### Rate Limit UX (#464) (2026-03-20) + +**Context:** Users hitting Copilot rate limits saw generic "Something went wrong processing your message." Squad hid the actual error. `squad doctor` reported nothing — useless to diagnose. + +**Root cause:** The catch block in `shell/index.ts` line ~1119 always emitted `genericGuidance()` unless `SQUAD_DEBUG=1`. Rate limit errors never got special treatment despite `RateLimitError` existing in `adapter/errors.ts`. + +**Fix:** +1. `error-messages.ts` — Added `rateLimitGuidance({ retryAfter?, model? })` and `extractRetryAfter(message)` utilities. Rate limit guidance shows clear message + recovery options (retry time, `squad economy on`, config.json model override). +2. `shell/index.ts` — Catch block now detects rate limits via `instanceof RateLimitError` OR regex on the raw message. Writes `.squad/rate-limit-status.json` on detection. +3. `doctor.ts` — Added `checkRateLimitStatus()` check. Reads status file and warns if rate limit was recent. +4. `test/error-messages.test.ts` — Added 11 new tests covering `rateLimitGuidance` and `extractRetryAfter`. + +**Pattern:** Rate limit status written to `.squad/rate-limit-status.json` as `{ timestamp, retryAfter, model, message }`. Doctor reads it on next run. File is never deleted automatically — doctor marks it `pass` when > 4h stale. + +**Import path for `RateLimitError`:** `@bradygaster/squad-sdk/adapter/errors` (subpath export, not in main barrel). + +**PR:** #464 fix — squad/464-rate-limit-ux + +### CLI Entry Point Architecture +cli-entry.ts is the central router for ~30+ CLI commands using dynamic imports (lazy-loading). Commands are routed via if-else blocks. Has a recurring "unwired command" bug class — implementations exist in cli/commands/ but aren't routed in cli-entry.ts. The cli-command-wiring.test.ts regression test catches this by verifying every .ts file in cli/commands/ is imported. + +### ESM Runtime Patch +Module._resolveFilename interceptor in cli-entry.ts (lines 47-54) patches broken ESM import in @github/copilot-sdk@0.1.32 (vscode-jsonrpc/node missing .js extension). Required for Node 24+ strict ESM enforcement. Works on npx cache hits where postinstall scripts don't run. + +### Lazy Import Pattern +All command imports use `await import('./cli/commands/xxx.js')` to minimize startup time. Copilot SDK is lazily loaded only when shell is invoked. All .js extensions required for Node 24+ strict ESM. + +### CLI Packaging & Distribution +`npm pack` produces a complete, installable tarball (~275KB packed, 1.2MB unpacked). Package includes dist/, templates/, scripts/, README.md per package.json "files" field. Postinstall script (patch-esm-imports.mjs) patches @github/copilot-sdk for Node 24+ compatibility. Tarball can be installed locally (`npm install ./tarball.tgz`) and commands execute via `node node_modules/@bradygaster/squad-cli/dist/cli-entry.js`. Both squad-cli and squad-sdk must be installed together — cli depends on sdk with "*" version specifier. All 27+ CLI commands are lazy-loaded at runtime; `--help` validates command routing without executing full logic. + +### Packaging Smoke Test Strategy +test/cli-packaging-smoke.test.ts validates the packaged artifact (not source). Uses npm pack + install in temp dir + command routing verification. Commands are expected to fail (no .squad/ dir) — test verifies routing only (no "Unknown command", no MODULE_NOT_FOUND for the command itself). Exception: node-pty is an optional dependency for the `start` command and MODULE_NOT_FOUND for node-pty is allowed. Windows cleanup requires retry logic due to EBUSY errors — use rmSync with maxRetries + retryDelay options, wrap in try/catch to fail silently since tests have passed. + +### v0.8.24 Release Readiness Audit +CLI completeness audit (2026-03-08) confirmed: 26 primary commands routed in cli-entry.ts, all present in smoke test. 4 aliases (watch→triage, workstreams→subsquads, remote-control→rc, streams→subsquads). 3 aliases tested, 1 untested ("streams"). Packaging verified: dist/, templates/, scripts/, README.md in tarball; bin entry points to dist/cli-entry.js; postinstall script included and working. All 32 smoke tests pass. Package.json files array correct. npm pack output shows 318 files, 275KB packed. No missing command implementations. Optional dep (node-pty) handled correctly. Only gap: "streams" alias not in smoke test (routed correctly but test coverage incomplete). Confidence: 95% — all critical paths covered, minor alias test gap non-blocking. + +📌 **Team update (2026-03-08T21:18:00Z):** FIDO + EECOM released unanimous GO verdict for v0.8.24. Smoke test approved as release gate. FIDO confirmed 32/32 pass + publish.yml wired correctly. EECOM confirmed 26/26 commands + packaging complete (minor gap: "streams" alias untested, non-blocking). + +### Cross-Platform Filename and Config Fixes (#348, #356) (2026-03-15T05:30:00Z) + +**Context:** Two cross-platform bugs broke Squad on Windows: (1) log filenames contained colons in ISO 8601 timestamps (illegal on Windows), (2) `.squad/config.json` contained absolute machine-specific `teamRoot` path. + +**Investigation:** +- Searched SDK for all timestamp usage in filenames — found `safeTimestamp()` utility already existed but wasn't consistently used +- `comms-file-log.ts` (line 32) used inline `toISOString().replace(/:/g, '-')` instead of utility +- `init.ts` (line 612) wrote absolute `teamRoot` to config.json on every init +- Session-store already used `safeTimestamp()` correctly (line 71) + +**Fixes:** +1. **Bug #348:** Updated `comms-file-log.ts` to import and use `safeTimestamp()` utility instead of inline timestamp formatting +2. **Bug #356:** Removed `teamRoot` field from config.json (can be computed at runtime via `git rev-parse --show-toplevel`) +3. Updated live `.squad/config.json` in repo to remove machine-specific path + +**Pattern:** Centralized timestamp formatting in `safeTimestamp()` utility (replaces colons + truncates milliseconds). Windows-safe format: `2026-03-15T05-30-00Z` instead of `2026-03-15T05:30:00.123Z`. + +**Test Impact:** All 150 tests pass. Communication adapter test doesn't validate specific filename format (structural test, not behavioral). + +**PR:** #404 opened targeting dev. + +### CastingEngine CLI Integration (#342) (2026-03-15T11:20:00Z) + +**Context:** CastingEngine class (Issue #138, M3-2) existed in SDK with curated universe templates (The Usual Suspects, Ocean's Eleven) but was completely bypassed during `squad init`. LLM picked arbitrary names, and charter generation used regex-based `personalityForRole()` instead of template backstories. + +**Investigation:** +- CastingEngine.castTeam() was never called in CLI flow +- coordinator.ts buildInitModePrompt() let LLM pick any universe without guidance +- cast.ts generateCharter() used fallback personality logic instead of engine data +- SDK exports two AgentRole types: broad one in casting-engine.ts, restrictive one in runtime/constants.ts + +**Integration Strategy (Augment, Not Replace):** +- LLM still proposes roles and team composition (the beloved casting experience) +- CastingEngine augments with curated names when universe is recognized +- Mapping: "The Usual Suspects" → 'usual-suspects', "Ocean's Eleven" → 'oceans-eleven' +- Unrecognized universes (Matrix, Alien, etc.) preserve LLM's arbitrary names + +**Implementation:** +1. Added `augmentWithCastingEngine()` in cast.ts to replace LLM names with engine characters +2. Updated coordinator prompt to suggest preferred universes (Usual Suspects, Ocean's Eleven) +3. Extended `generateCharter()` to use engine personalities/backstories when available +4. Attached `_personality` and `_backstory` to CastMember objects for charter generation +5. Role mapping: CLI role strings → engine AgentRole enum (lead, developer, tester, etc.) + +**Type Import Pattern:** +- Import CastingEngine from `@bradygaster/squad-sdk/casting` (not main barrel export) +- Use casting-engine.ts AgentRole type (9 roles) not runtime/constants.ts (6 roles) +- Partial mapping: unmapped roles log warning and skip engine casting + +**Tests:** +- Created test/casting-engine-integration.test.ts (5 tests, all pass) +- Validates augmentation for both universes, case-insensitive matching, fallback behavior +- All 45 existing cast-parser/casting tests still pass + +**PR:** #417 opened targeting dev. + + +### PR #427 Cross-Fork Rebase (2026-03-15T21:00:00Z) + +**Context:** PR #427 (PAO external communications Phase 1) conflicted with upstream/dev after team recast (#423 Usual Suspects → Apollo 13) and model updates. Cross-repo PR (diberry/squad → bradygaster/squad). Initial rebase attempts failed due to git worktree confusion — main worktree was checked out to a different branch, causing git checkout commands to silently switch to wrong branches. + +**Problem:** Git commands (checkout, rebase) kept switching to unrelated branches (squad/agent-on-disk-concept, squad/320-fix-migration-guide-version-local) mid-rebase. Root cause: main worktree at C:\Users\diberry\repos\project-squad\squad was checked out to squad/agent-on-disk-concept. Git was treating checkout commands as worktree operations and switching the main worktree's HEAD, aborting the rebase. + +**Solution:** Created dedicated worktree (.worktrees/pao-rebase) for the rebase operation. This isolated the rebase from main worktree state and prevented branch switching. + +**Conflict Resolution (3 files, 7 commits rebased):** +1. **.squad/agents/_alumni/mcmanus/charter.md** - Merged both rule sets: DOCS-TEST SYNC (from upstream reskill) and EXTERNAL COMMS, HUMANIZER, AUDIT TRAIL (from PR #427). Used PowerShell regex to extract and combine both sides. +2. **.squad/routing.md** - Accepted Apollo 13 team names (EECOM, PAO, FIDO) from upstream via `git checkout --ours` (in rebase context, "ours" = upstream, "theirs" = our branch). PAO external comms infrastructure is team-agnostic. +3. **.squad/agents/keaton/history.md** - Accepted deletion via `git rm` (file moved to _alumni in upstream recast). + +**Rebase Commits:** 7 commits from squad/426-pao-external-comms rebased onto upstream/dev (f87a7a5), covering #423 team reskill, #424 SDK switch, #425/#428 test parity, #429 model updates. + +**Force Push:** `git push origin squad/426-pao-external-comms --force-with-lease` succeeded. PR #427 comment posted via gh CLI. + +**Pattern:** When working with git worktrees, always create a dedicated worktree for complex operations (rebase, cherry-pick) to avoid main worktree state interference. Use `git worktree list` to diagnose unexpected branch switching. +### SDK Init Flow Deep Dive (2026-03-08) +Traced complete `squad init --sdk` flow end-to-end for unified PRD. Key findings: (1) Init flow has two phases: CLI init creates skeleton files, REPL auto-cast creates team members. (2) Critical gap: squad.config.ts is never updated after auto-cast — members exist in .squad/ but not in config. (3) Ralph is inconsistently created (auto-cast yes, CLI init no). (4) No commands exist for adding/removing members post-init. (5) CastingEngine class exists but is never called during init — LLM-based Init Mode prompt is used instead. Roadmap written to .squad/identity/sdk-init-implementation-roadmap.md with 7 fixes prioritized by dependency graph. Critical path: sync utility → Ralph fixes → CastingEngine integration → hire/remove commands. High-risk items: squad.config.ts AST parsing (considered regex alternative). Open questions: AST vs regex for config sync, CastingEngine augment vs replace LLM, Ralph always-on vs opt-in. + +📌 **Team update (2026-03-11T01:25:00Z):** SDK Init decisions finalized: Phase-based quality improvement program, CastingEngine canonical casting, squad.config.ts as source of truth, Ralph always-included, implementation priority order (sync utility first, then Ralph fixes, then CastingEngine integration). All decisions merged to decisions.md. Ready to start Phase 1 implementation. + +### Adoption Tracking Tier 1 Implementation (2026-03-10) +Implemented Flight's privacy-first adoption monitoring strategy on PR #326 branch. Moved `.squad/adoption/` → `.github/adoption/` for better GitHub integration. Stripped tracking.md to aggregate-only metrics (removed all individual repo names/URLs). Updated GitHub Action workflow (adoption-report.yml) and monitoring script (scripts/adoption-monitor.mjs) to write reports to `.github/adoption/reports/`. Removed "Built with Squad" showcase link from README.md (deferred to Tier 2 opt-in feature). This honors the principle: collect aggregate metrics via public APIs, but never publish individual repo lists without explicit consent. Test discipline: verified npm run build passes; docs-build.test.ts passed structure tests (Astro build failure unrelated to changes). Committed with clear message explaining privacy rationale. + +📌 **Team update (2026-03-10T12-55-49Z):** Adoption tracking Tier 1 complete and merged to decisions.md. Privacy-first architecture confirmed: aggregate metrics only, opt-in for individual repos, public showcase only when 5+ projects opt in. Append-only file governance enforced (no deletions in history.md or decisions.md). Microsoft ampersand style guide adopted for documentation. + +### Issue Triage (2026-03-22T06:44:01Z) + +**Flight triaged 6 unlabeled issues and filed 1 new issue.** + +EECOM assigned: +- **#481 (StorageProvider PRD)** → squad:control + squad:eecom (type system abstraction + runtime integration) +- **#479 (history-shadow race condition)** → squad:eecom + squad:retro (production bug; mitigation through StorageProvider atomicity) + +Pattern: Three architectural gaps identified (agent spec, state abstraction, quality tooling) + one production bug. StorageProvider abstraction critical for #479 atomicity fix. + +📌 **Team update (2026-03-22T06:44:01Z):** Flight issued comprehensive triage. EECOM owns StorageProvider PRD spec (#481) + history-shadow race mitigation (#479). Ready to begin implementation on next sprint. + +### PR #483 Review & Merge — Platform Adapter Timeout Fix (2026-03-22) + +Reviewed and merged diberry's fix for platform-adapter test timeouts that were blocking all 8 open PRs. Root cause: `getAvailableWorkItemTypes()` called `execFileSync('az', ...)` with no timeout — in CI where az CLI is installed but no real ADO org exists, it hangs indefinitely until Vitest kills it at 5s. + +**Fix pattern:** `{ ...EXEC_OPTS, timeout: 3_000 }` — spread existing exec options and add a 3-second timeout. The existing catch block already returns sensible default work item types, so timeout errors fall through gracefully. This is the correct pattern for any external CLI call that might hang: add a timeout to execFileSync and ensure the catch block has a fallback. + +**Rebase note:** Branch was already clean on top of dev (1 commit ahead, no divergence). No rebase was needed. + +📌 **Team update:** PR #483 merged (squash). This unblocks CI for all open PRs that were failing on platform-adapter test timeouts. The remaining CI failure across PRs is the broken docs link (separate issue). + +### PR #480 Review & Merge — History Race Condition Fix (2026-03-22) + +Reviewed and merged PR #480 (async mutex + atomic writes + 14 tests). Addresses race condition in history-shadow file operations under concurrent load. + +**Fix pattern:** Race conditions in history operations require three-layer defense: (1) async mutex for write serialization, (2) atomic file operations (write-then-rename), (3) comprehensive test coverage (14 tests for edge cases). This pattern applies to any persistent state under concurrent access. + +**Key learning:** File system race conditions aren't just "add a lock" — need atomicity guarantees (rename is atomic), serialization (mutex), and exhaustive test coverage to validate edge cases (concurrent writes, stale reads, partial failures). + +### PR #486 Review & Merge — SIGINT Handling (2026-03-22) + +Reviewed and merged PR #486 (two-layer signal handling + 22 tests). Improves graceful shutdown under SIGINT (Ctrl+C) by cleaning up both parent and child processes. + +**Fix pattern:** Signal handling in Node.js requires two layers: (1) parent process SIGINT handler that triggers graceful shutdown, (2) child process cleanup (kill child processes, close file handles, flush buffers). Incomplete cleanup leaves zombie processes or orphaned file locks. Test coverage essential: 22 tests verify process tree cleanup, signal propagation, and edge cases (nested children, immediate re-signals). + +**Key learning:** SIGINT handling is more complex than "add a signal handler" — need explicit child process cleanup logic + comprehensive tests. Pattern applies to any process spawning child processes (CLI spawning subshells, REPL spawning child REPL instances, etc.). +### Economy Mode Implementation (#500) (2026-03-20) + +**Context:** Issue #500 requested economy mode — a session-level and persistent modifier that shifts model selection to cheaper alternatives. + +**Architecture decision:** Economy mode is a Layer 3/4 modifier only. Layers 0–2 (explicit user preferences: config.json, session directive, charter) are never downgraded. This preserves user intent while enabling cost savings on auto-selected tasks. + +**Implementation:** +1. `ECONOMY_MODEL_MAP` + `applyEconomyMode()` in `config/models.ts` — pure mapping function for premium→standard and standard→fast downgrades +2. `readEconomyMode()` + `writeEconomyMode()` — config.json read/write functions (same merge-without-clobber pattern as `writeModelPreference()`) +3. `resolveModel()` in `config/models.ts` updated with `economyMode?: boolean` option; falls back to reading from `squadDir` if not provided +4. `resolveModel()` in `agents/model-selector.ts` updated with `economyMode?: boolean` — both SDK resolvers are economy-aware +5. `squad economy [on|off]` command in CLI for persistent toggle +6. `--economy` global flag in `cli-entry.ts` sets `SQUAD_ECONOMY_MODE=1` env var for session scope +7. 34 new tests in `test/economy-mode.test.ts` — all pass + +**Key pattern:** Both resolveModel implementations follow identical principle: explicit overrides (user choice) are sacred; economy only affects computed auto-selection. + +**PR:** #500 branch `squad/500-economy-mode` + +### node:sqlite Hard-Fail Fix (#502) (2026-03-21) + +**Context:** Workshop participants (reported by Doron Ben Elazar) were blocked by `ERR_UNKNOWN_BUILTIN_MODULE` crashes. `node:sqlite` (used by Copilot SDK for session storage) requires Node 22.5.0+. The existing soft-warn-and-continue approach let users limp into a cryptic crash. + +**Root cause:** `engines.node` said `>=20` but `node:sqlite` needs `>=22.5.0`. The pre-flight check warned but didn't exit, so users saw confusing failures deep in SDK code. + +**Fix:** +1. **cli-entry.ts:** Replaced `try { await import('node:sqlite') } catch { warn }` with a synchronous version check that calls `process.exit(1)` immediately with a clear upgrade message. Removed the now-dead `checkNodeSqlite()` function and its call site. +2. **doctor.ts:** Added `checkNodeVersion()` to `squad doctor` — exported with optional version param for testability. +3. **package.json (×3):** Corrected `engines.node` to `>=22.5.0` so npm/npx warn at install time. +4. **Tests:** 5 new tests for `checkNodeVersion()` (Node 20.x fail, 22.4.x fail, 22.5.0 pass, 24.x pass, current env pass). Updated check-count assertion. + +**Pattern:** git branch confusion — `git checkout -b` switches HEAD but edits to files on wrong branch are lost when switching. Always confirm `git branch` before making file edits. File edits don't follow you to a new branch if you forgot to switch first. + +**PR:** #506 branch `squad/502-node-sqlite-dependency` + +### Rate Limit Recovery UX (#464) (2026-03-22) + +**Context:** Rate limit errors showed generic message with no actionable recovery. Brady directive: offer model switching + economy mode as recovery options. + +**Implementation:** +1. `error-messages.ts` — `rateLimitGuidance()` shows actual reason + 3 recovery options (retry time, `squad economy on`, config.json model override) +2. `shell/index.ts` — Detects rate limits via `instanceof RateLimitError` or regex; writes `.squad/rate-limit-status.json` +3. `doctor.ts` — `checkRateLimitStatus()` reads status file and warns if recent +4. 36 new tests — all pass + +**PR:** #505 `squad/464-rate-limit-ux` — merged (rebased after #504) + +### Session 2 Summary (2026-03-22) + +Executed 3 tasks across 2 waves: economy mode (#500, PR #504), node:sqlite fix (#502, PR #506), rate limit UX (#464, PR #505). All PRs merged to dev. + + +### Personal Squad Init via npx (#576) (2026-03-23) + +**Context:** `init --global` (used via npx to set up personal squad) created a full `.squad/` structure at `~/.config/squad/` but never created the `personal-squad/` subdirectory. `resolvePersonalSquadDir()` looks for `personal-squad/`, so subsequent repo-level `init` couldn't discover the user's personal agents. + +**Root cause:** Two separate concepts - `init --global` scaffolds a full squad, `personal init` creates `personal-squad/`. The `--global` flag never bridged between them. + +**Fix:** +1. `resolution.ts` - Added `ensurePersonalSquadDir()` idempotent helper to SDK. +2. `cli-entry.ts` - `init --global` now suppresses workflows and passes `isGlobal` flag. +3. `init.ts` - After global init, calls `ensurePersonalSquadDir()`. After repo init, detects personal squad. +4. `personal.ts` - Refactored to reuse `ensurePersonalSquadDir()`. +5. `resolution.test.ts` - Added 3 tests. + +**Pattern:** `resolveGlobalSquadPath()` returns the container; `ensurePersonalSquadDir()` creates the subdirectory the rest of the system looks for. +📌 **Team update (2026-03-25T18:11Z):** Fixed #590 personal squad path regression — getPersonalSquadRoot() now uses canonical personal-squad/ subdirectory like esolvePersonalSquadDir() and nsurePersonalSquadDir(). Committed on squad/590-fix-personal-squad-root. FIDO found same bug in shell/index.ts → work passed to CONTROL for full sweep revision. Awaiting FIDO re-review. + diff --git a/.squad/agents/eecom/history.md b/.squad/agents/eecom/history.md index 07eb1d11f..5673d8773 100644 --- a/.squad/agents/eecom/history.md +++ b/.squad/agents/eecom/history.md @@ -116,4 +116,4 @@ Executed 3 tasks across 2 waves: economy mode (#500, PR #504), node:sqlite fix ( **Pattern:** `resolveGlobalSquadPath()` returns the container; `ensurePersonalSquadDir()` creates the subdirectory the rest of the system looks for. 📌 **Team update (2026-03-25T18:11Z):** Fixed #590 personal squad path regression — getPersonalSquadRoot() now uses canonical personal-squad/ subdirectory like -esolvePersonalSquadDir() and nsurePersonalSquadDir(). Committed on squad/590-fix-personal-squad-root. FIDO found same bug in shell/index.ts → work passed to CONTROL for full sweep revision. Awaiting FIDO re-review. +resolvePersonalSquadDir() and ensurePersonalSquadDir(). Committed on squad/590-fix-personal-squad-root. FIDO found same bug in shell/index.ts → work passed to CONTROL for full sweep revision. Awaiting FIDO re-review. diff --git a/.squad/agents/fido/history-archive-2026-08-19T13-11-34.130-07-00.md b/.squad/agents/fido/history-archive-2026-08-19T13-11-34.130-07-00.md new file mode 100644 index 000000000..9c88ff7c0 --- /dev/null +++ b/.squad/agents/fido/history-archive-2026-08-19T13-11-34.130-07-00.md @@ -0,0 +1,251 @@ +# FIDO + +> Flight Dynamics Officer + +## Core Context + +Quality gate authority for all PRs. Test assertion arrays (EXPECTED_GUIDES, EXPECTED_FEATURES, EXPECTED_SCENARIOS, etc.) MUST stay in sync with files on disk. When reviewing PRs with CI failures, always check if dev branch has the same failures — don't block PRs for pre-existing issues. 3,931 tests passing, 149 test files, ~89s runtime. + +📌 **Team update (2026-03-26T06:41:00Z — Crash Recovery Execution & Community PR Review):** Post-CLI crash recovery completed: Round 1 baseline verified (5,038 tests ✅ green), Round 2 executed duplicate closures (#605/#604/#602) and 9-PR community batch review. FIDO approved 3 PRs (#625 notification-routing, #603 Challenger agent, #608 security policy—merged via Coordinator) and issued change requests on 6 PRs identifying systemic issues: changeset package naming (4 PRs used unscoped `squad-cli` instead of `@bradygaster/squad-cli`); file paths (2 PRs placed files at root instead of correct package structure). Quality gate result: high-bar community acceptance—approved 3/9 (33%), change-request 6/9 (67%), 0 rejections. PR #592 (legacy, high-quality) also merged. All actions complete; dev branch remains green. + +📌 **Team update (2026-03-25T15:23Z — Triage Session & PR Review Batch):** FIDO reviewed 10 open PRs for quality and merge readiness. Identified 3 duplicate/overlap pairs consolidating 6 PRs into 4: #607 (retro enforcement, comprehensive) approved for merge, #605 closed as duplicate. #603 (Challenger agent, correct paths) approved, #604 closed as duplicate. #606 (tiered memory superset) approved, #602 closed as duplicate. Merge-ready: #611 (blocked on #610), #592 (joniba wiring guide, high-quality). Decisions merged. + +## Key Learnings + +### Test Assertion Sync Discipline +EXPECTED_* arrays in docs-build.test.ts must match filesystem reality. When PRs add new content files, verify the corresponding test arrays are updated. Consider dynamic discovery pattern (used for blog posts) for resilience against content additions. Stale assertions that block CI are FIDO's responsibility. **Fixed PR #331:** EXPECTED_SCENARIOS expanded to 25 entries, EXPECTED_FEATURES array created with 32 entries (commit 6599db6). +📌 **Team update (2026-03-26T06:41:00Z — Crash Recovery Execution & Community PR Review):** Post-CLI crash recovery completed: Round 1 baseline verified (5,038 tests ✅ green), Round 2 executed duplicate closures (#605/#604/#602) and 9-PR community batch review. FIDO approved 3 PRs (#625 notification-routing, #603 Challenger agent, #608 security policy—merged via Coordinator) and issued change requests on 6 PRs identifying systemic issues: changeset package naming (4 PRs used unscoped `squad-cli` instead of `@bradygaster/squad-cli`); file paths (2 PRs placed files at root instead of correct package structure). Quality gate result: high-bar community acceptance—approved 3/9 (33%), change-request 6/9 (67%), 0 rejections. PR #592 (legacy, high-quality) also merged. All actions complete; dev branch remains green. Decision inbox merged and deleted. Next: Monitor 6 change-request PRs for author responses. + +📌 **Team update (2026-03-25T15:23Z — Triage Session & PR Review Batch):** FIDO reviewed 10 open PRs for quality and merge readiness. Identified 3 duplicate/overlap pairs consolidating 6 PRs into 4: #607 (retro enforcement, comprehensive) approved for merge, #605 closed as duplicate (less comprehensive). #603 (Challenger agent, correct paths) approved for merge, #604 closed as duplicate (wrong file paths). #606 (tiered memory superset, 3-tier model) approved for merge, #602 closed as duplicate (narrower 2-tier scope). Merge-ready PRs identified: #611 (blocked on #610), #592 (joniba wiring guide, high-quality). Draft #567 not ready. Impact: reduces PR count from 10 to 7, eliminates file conflicts, preserves unique value. All other PRs (#611, #608, #592, #567) can proceed independently. Decisions merged to decisions.md and decisions inbox deleted. + +## Learnings + +### Test Assertion Sync Discipline +EXPECTED_* arrays in docs-build.test.ts must match filesystem reality. When PRs add new content files, verify the corresponding test arrays are updated. Consider dynamic discovery pattern (used for blog posts) for resilience against content additions. Stale assertions that block CI are FIDO's responsibility. + +### PR Quality Gate Pattern +Verdict scale: GO (merge), FAIL (block until fixed), NO-GO (reject). Always verify: test discipline (assertions synced), CI status (distinguish pre-existing vs new failures), content accuracy, cross-reference validity. When detecting CI failures, run baseline comparison (dev branch vs PR branch) to isolate regressions. + +### Name-Agnostic Testing +Tests reading live .squad/ files must assert structure/behavior, not specific agent names. Names change during team rebirths. Two test classes: live-file tests (survive rebirths, property checks) and inline-fixture tests (self-contained, can hardcode). + +### Dynamic Content Discovery +Blog tests use filesystem discovery (readdirSync) instead of hardcoded arrays. Pattern: discover from disk, sort, validate build output exists. + +### Command Wiring Regression Test +cli-command-wiring.test.ts prevents "unwired command" bug: verifies every .ts file in commands/ is imported in cli-entry.ts. Bidirectional validation. + +### CLI Packaging Smoke Test +cli-packaging-smoke.test.ts validates packaged CLI artifact (npm pack → install → execute). Tests 27 commands + 3 aliases. Catches: missing imports, broken exports, bin misconfiguration, ESM resolution failures. Windows cleanup requires retry logic (EBUSY errors) — use rmSync with maxRetries + retryDelay, wrap in try/catch. + +### Agent Name Extraction Test Coverage (#577) +Extracted inline regex-based agent name parsing from `shell/index.ts` into testable pure function `parseAgentFromDescription` in `shell/agent-name-parser.ts`. 30 tests across 7 categories. 3-tier matching: (1) leading emoji+name+colon regex, (2) name+colon anywhere, (3) fuzzy word-boundary match. Shell index.ts delegates to this function. + +### Init Scaffolding Completeness Tests (#579) +`test/init-scaffolding.test.ts` — 15 tests: casting directory scaffolding (verifies .squad/casting/ + all 3 JSON files), no-remote resilience (init succeeds without git remote), doctor validation after init (zero failures). Follows existing test conventions — vitest, randomBytes temp dirs in cwd, compiled dist imports. + +### Personal Squad Init Discovery Tests (#576) +`test/personal-squad-init.test.ts` — 35 tests, 10 describe blocks. Key finding: `resolvePersonalSquadDir()` is install-method-agnostic — resolves from env vars and `os.homedir()`, never from `process.argv`. npx issue #576 is NOT in path resolution but in CLI command wiring or `--global` flag routing. SDK layer works correctly. + +### Publish Policy CI Gate (#557) +Added `publish-policy` job to squad-ci.yml: scans `.github/workflows/*.yml` for bare `npm publish` commands missing `-w`/`--workspace`. `test/publish-policy.test.ts` (36 tests). Meta-references (echo, grep, YAML name keys) must be excluded from lint. + +### PR Review Batch — Community PRs +Community contributors consistently struggle with: (a) scoped npm package names in changesets (use `@bradygaster/squad-cli` not `squad-cli`), (b) monorepo file placement (skills in `packages/squad-cli/templates/skills/`). Both preventable with better contributor docs. Changeset package name mismatch is most common error (4/9 Tamir PRs). + +📌 **Team update (2026-07-29T17:11:56+10:00 — Issue #1556 / PR #1557):** A new required CI check `squad-workflow-lint` now exists in `.github/workflows/squad-workflow-lint.yml`. It runs actionlint 1.7.12 + shellcheck 0.10.0 against all 5 workflow/template directories, including the canonical `.squad-templates/workflows/` sources. FIDO should treat this as a required gate alongside existing CI checks — PRs that introduce SC2086, unquoted variables, or invalid action syntax in workflow files will fail this check. All known SC2086 findings across Squad's own workflows were fixed in PR #1557. +cli-packaging-smoke.test.ts validates packaged CLI artifact (npm pack → install → execute). Tests 27 commands + 3 aliases. Catches: missing imports, broken exports, bin misconfiguration, ESM resolution failures. Complements source-level wiring test. + +### CastingEngine Integration Review +CastingEngine augments LLM casting with curated names for recognized universes. Unrecognized universes preserve LLM names. Import from `@bradygaster/squad-sdk/casting`, use casting-engine.ts AgentRole type (9 roles). Partial mapping: unmapped roles skip engine casting. + +### PR #331 Quality Gate Review — NO-GO (Blocking Issues Found) (2026-03-10T14:13:00Z) + +**CRITICAL VIOLATIONS DETECTED:** + +1. **Stale Test Assertions (Hard Rule Violation)** — EXPECTED_SCENARIOS array in test/docs-build.test.ts contains only 7 values ['issue-driven-dev', 'existing-repo', 'ci-cd-integration', 'solo-dev', 'monorepo', 'team-of-humans', 'cross-org-auth'], but 25 scenario files exist on disk (aspire-dashboard, client-compatibility, disaster-recovery, keep-my-squad, large-codebase, mid-project, multi-codespace, multiple-squads, new-project, open-source, private-repos, release-process, scaling-workstreams, switching-models, team-portability, team-state-storage, troubleshooting, upgrading, + 7 in array). My charter: "When I add test count assertions, I MUST keep them in sync with the actual files on disk. Stale assertions that block CI are MY responsibility to prevent." This is MY responsibility to catch. + +2. **Missing EXPECTED_FEATURES Array** — PR adds 'features' to the sections list in test/docs-build.test.ts (line 46), but NO EXPECTED_FEATURES array exists. Test line 171 "all expected doc pages produce HTML in dist/" will skip features entirely. 32 feature files exist (.md files in docs/src/content/docs/features/). + +📌 **Team update (2026-03-11T01:27:57Z):** PR #331 quality gate resolved. FIDO fixed test assertion sync in docs-build.test.ts: EXPECTED_SCENARIOS updated to 25 entries, EXPECTED_FEATURES array created with 32 entries, test assertions updated for features validation. Tests: 6/6 passing. Commit: 6599db6. Blocking NO-GO converted to approval gate cleared. Lesson reinforced: test assertions must be synced to filesystem state; CI passing ≠ coverage. + +3. **Incomplete Test Coverage Sync** — PAO's history (line 41) states "Updated EXPECTED_SCENARIOS in docs-build.test.ts to match remaining files" after deleting ralph-operations.md and proactive-communication.md. But the diff shows ONLY a single-line change (adding 'features' to sections array). The full test update was not committed. + +**POSITIVE FINDINGS:** +- ✅ CI passed (test run completed successfully on GitHub) +- ✅ Markdown structure tests pass (6/6 syntax checks) +- ✅ Docs are well-written: sentence-case headings, active voice, present tense, second person +- ✅ Cross-references valid (labels.md link verified) +- ✅ No duplicate "How It Works" heading in reviewer-protocol.md +- ✅ Content intact (no accidental loss) +- ✅ Microsoft Style Guide compliance confirmed + +**ROOT CAUSE:** PAO staged the boundary review changes but the test update commit was incomplete. The assertion arrays must be synchronized before merge. + +**REQUIRED FIX:** Update test/docs-build.test.ts: +1. EXPECTED_SCENARIOS = [ all 25 actual scenario files, sorted ] +2. EXPECTED_FEATURES = [ all 32 actual feature files, sorted ] +3. Regenerate to match disk reality (use filesystem discovery if the project wants test-resilience) + +**VERDICT:** 🔴 **NO-GO** — Merge blocked until test assertions sync with disk state. This is a quality gate violation. + +### Test Assertion Sync Fix (2026-03-10T14:20:00Z) + +**Issue resolved:** Fixed stale test assertions in test/docs-build.test.ts identified during PR #331 review. + +**Changes made:** +1. Expanded EXPECTED_SCENARIOS from 7 to 25 entries (matched all .md files in docs/src/content/docs/scenarios/) +2. Added EXPECTED_FEATURES array with 32 entries (matched all .md files in docs/src/content/docs/features/) +3. Updated test logic to include features section in HTML build validation + +**Validation:** All structure validation tests passing (6/6). Build tests skipped as expected (Astro not installed). Arrays now accurately reflect disk state. + +**Commit:** 6599db6 on branch squad/289-squad-dir-explainer + +**Learning:** When test assertions reference file counts, they MUST be kept in sync with disk reality. The principle applies to ALL assertion arrays (EXPECTED_SCENARIOS, EXPECTED_FEATURES, EXPECTED_GUIDES, EXPECTED_REFERENCE, etc.). Consider dynamic discovery pattern (used in EXPECTED_BLOG) for resilience against content additions. + +📌 **Team update (2026-03-10T14-44-23Z):** PR #310 scroll flicker fix merged. 4 root causes identified: Ink clearTerminal issue, timer amplification, log-update trailing newline, unstable Static keys. Postinstall patch pattern adopted for Ink internals. Version pin recommended for stability gate. Build: 3,931 tests pass, zero regressions. +### PR #331 Quality Gate Review — NO-GO (Blocking Issues Found) (2026-03-10T14:13:00Z) + +**CRITICAL VIOLATIONS DETECTED:** + +1. **Stale Test Assertions (Hard Rule Violation)** — EXPECTED_SCENARIOS array in test/docs-build.test.ts contains only 7 values ['issue-driven-dev', 'existing-repo', 'ci-cd-integration', 'solo-dev', 'monorepo', 'team-of-humans', 'cross-org-auth'], but 25 scenario files exist on disk (aspire-dashboard, client-compatibility, disaster-recovery, keep-my-squad, large-codebase, mid-project, multi-codespace, multiple-squads, new-project, open-source, private-repos, release-process, scaling-workstreams, switching-models, team-portability, team-state-storage, troubleshooting, upgrading, + 7 in array). My charter: "When I add test count assertions, I MUST keep them in sync with the actual files on disk. Stale assertions that block CI are MY responsibility to prevent." This is MY responsibility to catch. + +2. **Missing EXPECTED_FEATURES Array** — PR adds 'features' to the sections list in test/docs-build.test.ts (line 46), but NO EXPECTED_FEATURES array exists. Test line 171 "all expected doc pages produce HTML in dist/" will skip features entirely. 32 feature files exist (.md files in docs/src/content/docs/features/). + +📌 **Team update (2026-03-11T01:27:57Z):** PR #331 quality gate resolved. FIDO fixed test assertion sync in docs-build.test.ts: EXPECTED_SCENARIOS updated to 25 entries, EXPECTED_FEATURES array created with 32 entries, test assertions updated for features validation. Tests: 6/6 passing. Commit: 6599db6. Blocking NO-GO converted to approval gate cleared. Lesson reinforced: test assertions must be synced to filesystem state; CI passing ≠ coverage. + +3. **Incomplete Test Coverage Sync** — PAO's history (line 41) states "Updated EXPECTED_SCENARIOS in docs-build.test.ts to match remaining files" after deleting ralph-operations.md and proactive-communication.md. But the diff shows ONLY a single-line change (adding 'features' to sections array). The full test update was not committed. + +**POSITIVE FINDINGS:** +- ✅ CI passed (test run completed successfully on GitHub) +- ✅ Markdown structure tests pass (6/6 syntax checks) +- ✅ Docs are well-written: sentence-case headings, active voice, present tense, second person +- ✅ Cross-references valid (labels.md link verified) +- ✅ No duplicate "How It Works" heading in reviewer-protocol.md +- ✅ Content intact (no accidental loss) +- ✅ Microsoft Style Guide compliance confirmed + +**ROOT CAUSE:** PAO staged the boundary review changes but the test update commit was incomplete. The assertion arrays must be synchronized before merge. + +**REQUIRED FIX:** Update test/docs-build.test.ts: +1. EXPECTED_SCENARIOS = [ all 25 actual scenario files, sorted ] +2. EXPECTED_FEATURES = [ all 32 actual feature files, sorted ] +3. Regenerate to match disk reality (use filesystem discovery if the project wants test-resilience) + +**VERDICT:** 🔴 **NO-GO** — Merge blocked until test assertions sync with disk state. This is a quality gate violation. + +### Test Assertion Sync Fix (2026-03-10T14:20:00Z) + +**Issue resolved:** Fixed stale test assertions in test/docs-build.test.ts identified during PR #331 review. + +**Changes made:** +1. Expanded EXPECTED_SCENARIOS from 7 to 25 entries (matched all .md files in docs/src/content/docs/scenarios/) +2. Added EXPECTED_FEATURES array with 32 entries (matched all .md files in docs/src/content/docs/features/) +3. Updated test logic to include features section in HTML build validation + +**Validation:** All structure validation tests passing (6/6). Build tests skipped as expected (Astro not installed). Arrays now accurately reflect disk state. + +**Commit:** 6599db6 on branch squad/289-squad-dir-explainer + +**Learning:** When test assertions reference file counts, they MUST be kept in sync with disk reality. The principle applies to ALL assertion arrays (EXPECTED_SCENARIOS, EXPECTED_FEATURES, EXPECTED_GUIDES, EXPECTED_REFERENCE, etc.). Consider dynamic discovery pattern (used in EXPECTED_BLOG) for resilience against content additions. + +### Issue Triage (2026-03-22T06:44:01Z) + +**Flight triaged 6 unlabeled issues and filed 1 new issue.** + +FIDO assigned: +- **#477 (Code Quality Linting PRD)** → squad:fido (monorepo async/promise quality, ESLint 9 PoC ready) + +Pattern: Quality tooling gap identified. ESLint 9 modernization + async/promise pattern enforcement for monorepo. + +📌 **Team update (2026-03-22T06:44:01Z):** Flight issued comprehensive triage. FIDO owns Code Quality Linting PRD (#477). ESLint 9 PoC already drafted; ready for implementation planning. + +### Agent Name Extraction Test Coverage (#577) + +Extracted inline regex-based agent name parsing from `shell/index.ts` into a testable pure function `parseAgentFromDescription` in `shell/agent-name-parser.ts`. Created 30 tests across 7 categories: happy path, emoji variations, case insensitivity, fuzzy fallback, no-match, edge cases, and adversarial inputs. The function uses a 3-tier matching strategy: (1) leading emoji+name+colon regex, (2) name+colon anywhere regex, (3) fuzzy word-boundary match against known agent names. Shell index.ts now imports and delegates to this function. Build and tests green. + +**Learning:** Inline regex logic in UI code is untestable and fragile. Extracting to a pure function with explicit inputs (description string + known names array) makes it trivially testable and enables VOX's parallel fix to land cleanly. + +📌 **Team update (2026-03-23T23:15Z):** Orchestration complete. Agent name extraction refactor shipped: FIDO's parser module (30 tests, all passing), VOX's 3-tier cascading patterns, Procedures' spawn template standardization. All decisions merged to decisions.md. Agent IDs now display correctly in Copilot CLI. Canonical patterns: `agent-name-parser.ts` is source of truth for extraction logic. +### Init Scaffolding Completeness Tests (#579) + +Added `test/init-scaffolding.test.ts` — 15 tests covering three gaps exposed by issue #579: + +1. **Casting directory scaffolding** — After `initSquad()` and `runInit()`, verifies `.squad/casting/` directory and all three JSON files (registry.json, policy.json, history.json) exist and parse as valid JSON. Also confirms re-init does not overwrite existing casting files. + +2. **No-remote resilience** — Confirms init succeeds without errors when: git repo has no remote configured, brand-new `git init` repo, or no git at all. Uses `execFileSync` to create isolated git repos in temp dirs. + +3. **Doctor validation after init** — Runs `runDoctor()` against a freshly-initialized directory and asserts zero failures, specifically that `casting/registry.json exists` check passes. Also tests negative cases (missing file → fail, corrupt JSON → fail). + +Pattern: Tests follow existing `test/cli/init.test.ts` and `test/cli/doctor.test.ts` conventions — vitest, `randomBytes` temp dirs in cwd, imports from compiled dist via package exports (`@bradygaster/squad-cli/core/init`, `@bradygaster/squad-cli/commands/doctor`, `@bradygaster/squad-sdk`). + +Commit: 7660a27 on branch squad/579-init-scaffolding-hardening. + +### Personal Squad Init Discovery Tests (#576) + +**Task:** Write tests for personal squad discovery and init flows (Issue #576 — npx init --global not discovering personal squad). + +**Test file:** `test/personal-squad-init.test.ts` — 35 tests, 10 describe blocks, all passing. + +**Coverage areas:** +1. `resolveGlobalSquadPath()` — platform-specific path resolution (Windows APPDATA, Linux XDG_CONFIG_HOME, consistency) +2. `resolvePersonalSquadDir()` — kill-switch (SQUAD_NO_PERSONAL), directory existence, npx-agnostic discovery +3. `personalInit` contract — directory structure creation, config.json shape, idempotency +4. `resolveSquadPaths()` — personalDir field inclusion, null when disabled +5. Edge: empty personal-squad dir (exists but no agents/) +6. Edge: partial state (agent dirs without charter.md, missing Role metadata defaults to "personal", stray files skipped) +7. `mergeSessionCast()` — project-wins precedence, case-insensitive collision, empty inputs +8. `ensureSquadPathTriple()` — personal dir in allowed roots, null personalDir graceful handling +9. Charter metadata parsing edge cases (whitespace trimming, sourceDir correctness, multi-agent discovery) + +**Key finding:** `resolvePersonalSquadDir()` is install-method-agnostic — it resolves from env vars and `os.homedir()`, never from `process.argv`. The npx issue (#576) is therefore NOT in path resolution but likely in the CLI command wiring or the `--global` flag routing. Tests confirm the SDK layer works correctly. + +**Commit:** c307187 on branch squad/576-personal-squad-init-npx +### Publish Policy CI Gate (#557) + +Added `publish-policy` job to squad-ci.yml — lightweight lint that scans all `.github/workflows/*.yml` for bare `npm publish` commands missing `-w`/`--workspace`. Catches the incident class where root package.json gets published instead of a workspace package. Also wrote `test/publish-policy.test.ts` (36 tests) covering: workspace-scoped passes, bare publish fails, comment/echo/grep/YAML-name line skipping, findViolations line numbering, and live validation of all 15 workflow files. Key pattern: meta-references (echo, grep, YAML name keys containing "npm publish") must be excluded from lint — the CI script's own text would otherwise self-trigger. + +📌 **Team update (2026-03-24T06-release-hardening):** Publish policy CI gate (#557) implemented. Added `publish-policy` job to squad-ci.yml: lightweight lint scans `.github/workflows/*.yml` for bare `npm publish` commands, rejects non-workspace-scoped invocations. Wrote test/publish-policy.test.ts (36 tests) validating: workspace-scoped passes, bare publish fails, meta-reference (echo/grep/YAML-name) skipping, live validation of 15 workflow files. Pattern: catch "publish root package.json" incident class before merge. Both lint + playbook docs create enforcement + education loop. + +### PR Review Batch — 10 Open PRs (2026-03-24) + +Reviewed all 10 open PRs for quality, test coverage, and merge readiness. + +**Critical finding — Duplicate/overlapping PRs (tamirdresher):** +- **PRs #607 / #605** overlap on retrospective ceremony — both add weekly retro ceremony with Ralph enforcement. #607 adds ceremony + enforcement skill + guide (444 lines), #605 modifies existing templates/ceremonies.md + ralph-reference.md (217 lines). Both solve the same problem (retro enforcement) with different file structures. #607 is more comprehensive (includes enforcement guide + pseudocode), #605 is more concise (inline in existing templates). **Verdict: Pick one** — recommend #607 (standalone ceremony file is more discoverable). +- **PRs #604 / #603** are complete duplicates — both add Challenger agent template + fact-checking skill. #604 has `templates/challenger.md` (153 lines), #603 has `.squad/templates/agents/challenger.md` + `.squad/skills/fact-checking/SKILL.md` (133 lines). File locations differ but content is nearly identical. **Verdict: Close one as duplicate** — recommend #603 (file locations match project conventions). +- **PRs #606 / #602** overlap on tiered memory/history — #606 adds tiered-memory skill (hot/cold/wiki tiers, 370 lines), #602 adds tiered-history skill (hot/cold split, 158 lines). #606 is broader (3 tiers, scribe integration, spawn templates), #602 is narrower (2 tiers, history.md only). Both cite same production data source. **Verdict: #606 supersedes #602** — recommend closing #602 as subset. + +**Quality assessment:** +- **PR #611 (TypeDoc API):** CI passing, large well-scoped PR (1569 additions), includes tests (Playwright), screenshots provided, PAO reviewed. Ready to merge pending PAO's requested fixes (crosslink banner, nav URL simplification). Quality: HIGH. +- **PR #608 (Security policy):** Trivial (28 lines), no tests needed, no CI configured. Adds SECURITY.md with standard vulnerability reporting text. Quality: ACCEPTABLE (minor typo: "timely manor" → "timely manner"). +- **PR #592 (Enforcement wiring):** Well-documented (549 additions), adds missing step to hiring process + 3 appendices. CI passing, no code changes, docs-only. Quality: HIGH. +- **PR #567 (StorageProvider):** DRAFT status, clean implementation (321 additions), 18 tests passing, Wave 1 foundation PR (no call-site migration yet). Quality: HIGH, but keep as DRAFT until Wave 2 ready. + +**CI status:** 9/10 PRs have CI passing. #608 (security policy) has no CI configured on branch "patch-1" (external contributor branch). + +**Test coverage:** +- #611: Playwright tests included (8 tests) +- #607, #605, #604, #603, #606, #602: All docs-only, no tests needed +- #592: Docs-only, no tests needed +- #567: 18 tests included, all passing + +**Overlap resolution needed:** tamirdresher has 6 PRs, 3 pairs have significant overlap. Recommend: merge #607 (not #605), merge #603 (close #604), merge #606 (close #602). + +**Blocking issues:** +- None for mergeability — all non-overlapping PRs are technically ready +- Deduplication decision needed for tamirdresher's PRs before merging any of them + +### Community PR Batch Review — Post-Crash Recovery (2026-03-26) + +Reviewed 9 community PRs (8 from tamirdresher, 1 from eric-vanartsdalen). Key findings: + +1. **Changeset package name pattern:** 4 of 8 Tamir PRs (#623, #622, #621, #614) use unscoped `"squad-cli"` / `"squad-sdk"` instead of `"@bradygaster/squad-cli"` / `"@bradygaster/squad-sdk"`. Only #625 got this right. This is a recurring community contributor mistake — consider adding guidance to CONTRIBUTING.md or PR template. + +2. **File path pattern:** PRs #607 and #606 place files at root `ceremonies/`, `skills/`, `docs/`, `templates/` directories that don't exist. Skills belong in `packages/squad-cli/templates/skills/` and SDK equivalent. Community contributors don't know the monorepo layout. + +3. **Verdicts:** ✅ MERGE: #625 (notification-routing), #603 (Challenger agent), #608 (SECURITY.md). ⚠️ NEEDS CHANGES: #623, #622, #621, #614 (changeset fix), #607, #606 (path restructuring). + +**Learning:** Community contributors consistently struggle with two things: (a) scoped npm package names in changesets, and (b) monorepo file placement. Both are preventable with better contributor docs. + diff --git a/.squad/agents/flight/history-archive-2026-08-19T13-11-34.130-07-00.md b/.squad/agents/flight/history-archive-2026-08-19T13-11-34.130-07-00.md new file mode 100644 index 000000000..03aa6de4d --- /dev/null +++ b/.squad/agents/flight/history-archive-2026-08-19T13-11-34.130-07-00.md @@ -0,0 +1,209 @@ +# Flight — Project History + +> Knowledge accumulated through leading Squad development. + +--- + +📌 **Team update (2026-03-26T06:41:00Z — Crash Recovery Execution Complete):** Post-CLI crash recovery executed in 3 rounds. Round 1: Flight audited PR/issue state (found #617 merged, #619 conflicting, 3 dupes #605/#604/#602 open); FIDO verified baseline (5,038 tests ✅ green); Scribe merged stale inbox. Round 2: Flight closed 3 duplicate PRs with rationale; Procedures rebased PR #619 (model catalog) onto dev, resolved 3 merge conflicts, merged; FIDO reviewed 9 community PRs—approved 3 (#625/#603/#608), requested changes on 6 (package naming, file paths). Round 3: Coordinator merged 3 approved PRs. **10 PRs merged total** (6 merge-plan, 3 community, 1 legacy #592). **3 PRs closed** as duplicates. **6 PRs awaiting author revisions**. **Dev branch green** (5,038 tests). All merge-plan sequence complete. + +📌 **Team update (2026-03-25T15:23Z — Triage Session & PR Review):** Flight triaged 14 untriaged GitHub issues, created prioritized work session plan. Identified high-value quick wins (P1): #610 (docs broken link), #590 (getPersonalSquadRoot bug, P0), #591 (hiring wiring docs). Deferred community feature contributions (#601–#595) pending PR review. FIDO reviewed 10 open PRs, identified 3 duplicate/overlap pairs. Work session priority: #610→PAO, #590→EECOM, #592/#611→Flight review, #588→Procedures. Tamir PRs require proposal-first discipline. Merge-ready: #611 (blocked on #610), #592. + +📌 **Team update (2026-03-23T22:00Z — Release Crisis Recovery):** v0.9.0→v0.9.1 incident resolved. Released v0.9.1 stable on npm after 8-hour debugging marathon. Root causes: dependency validation gap (file: refs in packages), GitHub workflow cache race, npm workspace publish automation broken, no pre-publish verification. Created comprehensive retrospective with 5 root causes and 6 action items (A1–A6). Filed 9 GitHub issues (#556–#564). Pre-flight job added to publish pipeline. Surgeon charter hardened. 10 community PRs merged. Release process skill created at `.squad/skills/release-process/SKILL.md`. + +📌 **Team update (2026-03-22T09-35Z — Wave 1):** Ambient personal squad design validated and 19-task implementation plan authored across 4 PRs. EECOM executing Phase 1–2 (SDK + CLI), Procedures executing Phase 3 (governance) concurrently. All design gaps resolved; dependency graph established. +📌 **Team update (2026-03-26T06:41:00Z — Crash Recovery Execution Complete):** Post-CLI crash recovery executed in 3 rounds. Round 1: Flight audited PR/issue state (found #617 merged, #619 conflicting, 3 dupes #605/#604/#602 open); FIDO verified baseline (5,038 tests ✅ green); Scribe merged stale inbox. Round 2: Flight closed 3 duplicate PRs with rationale; Procedures rebased PR #619 (model catalog) onto dev, resolved 3 merge conflicts, merged; FIDO reviewed 9 community PRs—approved 3 (#625/#603/#608), requested changes on 6 (package naming, file paths). Round 3: Coordinator merged 3 approved PRs. **10 PRs merged total** (6 merge-plan, 3 community, 1 legacy #592). **3 PRs closed** as duplicates. **6 PRs awaiting author revisions**. **Dev branch green** (5,038 tests). All merge-plan sequence complete. Draft #567 parked pending requirements. Decision inbox merged to decisions.md and deleted. Next: Monitor change-request PRs for author responses. + +📌 **Team update (2026-03-25T15:23Z — Triage Session & PR Review):** Flight triaged 14 untriaged GitHub issues, created prioritized work session plan. Identified high-value quick wins (P1): #610 (docs broken link, 5-min fix), #590 (getPersonalSquadRoot bug, P0), #591 (hiring wiring docs). Deferred community feature contributions (#601–#595) pending PR review. Categorized maintenance (P2) and questions for community. FIDO reviewed 10 open PRs, identified 3 duplicate/overlap pairs (6 PRs consolidate to 4: merge #607/#603/#606, close #605/#604/#602). Work session priority: #610→PAO, #590→EECOM, #592/#611→Flight review, #588→Procedures. Established PR review strategy: Tamir PRs require proposal-first discipline before review. Merge-ready identified: #611 (blocked on #610), #592 (joniba wiring guide, high-quality). A2A protocol PRs remain shelved. All 14 issues fully categorized with squad assignments. Decision inbox merged to decisions.md. Session complete; team ready for execution. + +📌 **Team update (2026-03-23T22:00Z — Release Crisis Recovery):** v0.9.0→v0.9.1 incident resolved. Released v0.9.1 stable on npm after 8-hour debugging marathon (should have been 10 min). Root causes: dependency validation gap (file: refs in packages), GitHub workflow cache race, npm workspace publish automation broken, coordinator decision-making under pressure, no pre-publish verification. Created comprehensive retrospective with 5 root causes and 6 action items (A1–A6). Filed 9 GitHub issues (#556–#564) documenting release process improvements. Pre-flight job added to publish pipeline (dependency scanning + semver validation). Surgeon charter hardened with release governance rules. 10 community PRs merged (#569, #570, #571, #555, #552, #568, #572, #513, #573, #574). Discussion board fully triaged (15 discussions: 4 closed, 1 consolidated, 2 converted to issue, 8 kept). Dark mode fix deployed to production. Release process skill created at `.squad/skills/release-process/SKILL.md`. 9 GitHub issues filed for release improvements. Team ready for next cycle. + +📌 **Team update (2026-03-22T09-35Z — Wave 1):** Ambient personal squad design validated and 19-task implementation plan authored across 4 PRs (Phase 1 SDK, Phase 2 CLI, Phase 3 governance, Phase 4 tests). MVP = PR #1 + PR #3. EECOM executing Phase 1–2 (SDK + CLI), Procedures executing Phase 3 (governance) concurrently. All design gaps resolved; dependency graph established. Procedures wrote governance proposals for personal squad + economy mode — awaiting your review. Sims to execute Phase 4 after Phase 1+2 merge. Directive captured: bug #502 (node:sqlite, P1) to be picked up after Wave 1. No blocking issues — ready for execution. + +## Core Context + +Three-branch model (main/dev/insiders). Apollo 13 team, 3931 tests. Boundary review heuristic: "Squad Ships It" — if Squad doesn't ship the code, it's IRL content. Proposal-first: meaningful changes need docs/proposals/ before code. Two-error lockout policy: agent locked out after 2 errors in a session. Test name-agnosticism: framework tests must never depend on dev team's agent names. + +## Historical Learnings Summary (condensed) + +- **Issue filing pattern:** When a major incident occurs, file 9+ GitHub issues documenting root causes and improvements. One issue per root cause + one per action item. Creates accountability and accelerates fixes. +- **Release governance:** Brady established strict governance — Surgeon owns all publishing; strict playbook adherence; CI/CD is top priority; pre-flight gates mandatory before any release tagging. +- **Adoption tracking architecture:** Three-tier opt-in system: Tier 1 (aggregate-only `.github/adoption/`), Tier 2 (opt-in registry), Tier 3 (public showcase ≥5 projects). `.squad/` is team state only. +- **Content triage skill:** "Squad Ships It" litmus test. Triggered by `content-triage` label. Output: boundary analysis, sub-issues for PAO, IRL reference for Scribe. +- **Sprint prioritization:** Rank by: (1) bugs with active user impact, (2) quality/test gaps blocking GA, (3) high-ROI features unblocking downstream work. Interleave stability + velocity. +- **Distributed mesh integration:** Zero code changes. Convention-first additive layer (skills + scripts + docs). 125:1 ratio. mesh.json stays separate from squad.config.ts. +- **Remote squad access:** Three-phase rollout: Phase 1 GitHub Discussions bot (1 day, zero hosting), Phase 2 Copilot Extension via Contents API (1 week), Phase 3 Slack/Teams bot (2 weeks). Must solve `.squad/` context access. +- **PR #331 boundary review:** "Squad Ships It" pattern — remove external infrastructure docs, reframe platform integration docs, keep Squad behavior/config docs. +- **SDK Init Shore-Up PRD:** 6 SDK issues consolidated into 3-phase initiative: Phase 1 fixes gaps (config sync, built-in member exclusion), Phase 2 wires CastingEngine, Phase 3 test matrix. Owners: EECOM + CAPCOM. +- **Ambient personal squad (#329/#344):** 5 gaps identified: resolvePersonalAgents() function, ghost protocol for orchestration log, --team-root scope, squad personal init command, SQUAD_NO_PERSONAL env var. ensureSquadPathTriple() required in resolution.ts to enforce ghost protocol. +- **Release hardening plan:** PUBLISH-README.md rewrite (#564, absorbs #558-560), CI lint rule rejecting non-workspace npm publish (#557), ghost workflow deletion (#562). Lint rule: scan `.github/workflows/*.yml` for `npm publish` without `-w` flag. +- **Issue triage (2026-03-24 — 14 issues):** P0: #590 (getPersonalSquadRoot broken). P1: #610 (broken docs), #591 (hiring wiring). P2: #597, #588, #554. Questions: #589, #494. Deferred: #581 (ADO PRD, blocked until #341). +- **Community PR quality tiers:** Diberry (MSFT-level, architecturally-sound, merge-ready). Joniba (consistently high-quality, matches team standards). Tamir (technically strong, needs proposal-first discipline + monorepo placement guidance). +## Learnings + +### Issue Filing Patterns (2026-03-23 Release Incident) +When a major incident occurs, file 9+ GitHub issues documenting root causes and improvements. Pattern: one issue per root cause + one per action item. Use descriptive titles linking to specific improvements (e.g., "#556 Dependency validation in pre-publish checks"). Let team pick up issues in priority order. This accelerates fixes and creates accountability. + +### Release Governance Directives (2026-03-23) +Brady established strict release governance: (1) Surgeon owns all publishing (not Coordinator); (2) strict adherence to playbook; (3) document problems so they don't recur; (4) CI/CD is top priority; (5) written playbooks for everything; (6) no improvisation. Captured for team memory and enforced in team decisions. + +### Adoption Tracking Architecture +Three-tier opt-in system: Tier 1 (aggregate-only, `.github/adoption/`) ships first; Tier 2 (opt-in registry) designed next; Tier 3 (public showcase) launches when ≥5 projects opt in. `.squad/` is for team state only, not adoption data. Never list individual repos without owner consent. + +### Remote Squad Access +Three-phase rollout: Phase 1 — GitHub Discussions bot with `/squad` command (1 day, zero hosting). Phase 2 — GitHub Copilot Extension via Contents API (1 week). Phase 3 — Slack/Teams bot (2 weeks). Constraint: any remote solution must solve `.squad/` context access. + +### Content Triage Skill +"Squad Ships It" litmus test codified into reusable workflow. Triggered by `content-triage` label. Output: boundary analysis, sub-issues for PAO (doc extraction), IRL reference for Scribe. Content labels: `content:blog`, `content:sample`, `content:video`, `content:talk`. + +### Distributed Mesh Integration +Zero code changes. Skill files in templates/skills/, scripts in scripts/mesh/, docs in features/. mesh.json stays separate from squad.config.ts. Convention-first additive layer — invisible if unused. 125:1 ratio (30 lines of script vs 3,756 lines of deleted federation code). + +### Sprint Prioritization Pattern +Rank by: (1) bugs with active user impact, (2) quality/test gaps blocking GA, (3) high-ROI features unblocking downstream work. Interleave stability (bugs/quality) with velocity (features) across sprint capacity. + +**Updated wisdom.md with 4 patterns + 2 anti-patterns from recent work:** Test name-agnosticism for team rebirths, dynamic filesystem discovery for evolving content, cli-entry.ts unwired command bug pattern, bump-build.mjs version mutation timing, invalid semver formats, git reset data loss. + +**Issue triage attempted for 30 open issues:** Identified 10 unlabeled issues requiring squad assignment. Enterprise Managed User permissions blocked GitHub API label updates via `gh issue edit`. Triage analysis complete: +- SDK issues (#337, #342) → squad:eecom + squad:capcom (init flow + casting engine) +- Personal squad (#343, #344) → squad:flight (architecture territory) +- A2A protocol (#332-336) → squad:flight + domain experts (network, vox, retro, eecom) +- Tooling layers (#330) → squad:eecom + squad:procedures +Manual label application needed by repo owner. + +**SDK Init Shore-Up PRD created:** Consolidated 6 SDK-related issues (#337-342, #340-341) into unified 3-phase initiative at `.squad/identity/prd-sdk-init-shoreup.md`. Root causes: config sync gap, built-in member exclusion (Ralph, @copilot), CastingEngine bypass. Solution: Phase 1 fixes gaps (P1), Phase 2 wires CastingEngine (P1), Phase 3 exercises full test matrix (P2). Estimated 4 sprints to 100% SDK feature parity. Owners: EECOM + CAPCOM (phases 1-2), FIDO + CAPCOM (phase 3). + +📌 **Team update (2026-03-11T01:25:00Z):** Flight completed 30-issue triage + unified SDK Init Shore-Up PRD. CAPCOM + EECOM completed deep technical analysis + implementation roadmap. 5 decisions merged to decisions.md: Phase-based quality improvement program, CastingEngine canonical casting, squad.config.ts as source of truth, Ralph always-included, implementation priority order. + +### Issue Triage & PR Pipeline (2026-03-22) + +**Triaged 6 unlabeled issues:** Assigned to appropriate squad members per domain expertise and team capacity. Applied `next-up` label to 10 priority items (bugs, easy wins, docs improvements). All triaged issues now have clear ownership and next steps. + +**PR Pipeline:** Reviewed and rebased 8 PRs across EECOM, GNC, and PAO. All merged successfully. Key patterns documented for team reuse: +- **az CLI timeouts** (PR #483): External CLI calls need explicit timeouts + fallback handling +- **History race conditions** (PR #480): File operations require mutex + atomic writes + exhaustive tests +- **Signal handling** (PR #486): SIGINT cleanup needs two-layer approach (parent + child cleanup) +- **ESM exports** (PR #474): Node 22 compatibility requires exports map + file existence validation +- **Broken docs links** (PR #487): Automated link validation should be CI gate + +Test coverage expanded: 36 new tests (EECOM) + 4655+ total passing (GNC report). + +**Coordinator actions:** Filed #488 (GitHub auth documentation), created `next-up` label, labeled 10 priority issues for next sprint focus. +📌 **Team update (2026-03-10T12-55-49Z):** Adoption tracking architecture finalized. Three-tier system approved: Tier 1 (aggregate-only, `.github/adoption/`) shipping with PR #326; Tier 2 (opt-in registry) designed for next PR; Tier 3 (public showcase) launches when ≥5 projects opt in. Append-only file governance rule enforced to prevent data loss. Microsoft ampersand style guide adopted for all user-facing documentation. + +### PR #331 Review — Boundary Review Pattern Reinforced (2026-03-10) +Approved PR #331 ("docs: scenario and feature guides from blog analysis") for merge. PAO's boundary review (remove external infrastructure docs, reframe platform features to clarify scope, keep Squad behavior/config docs) was executed correctly. Key decisions: (1) ralph-operations.md and proactive-communication.md deleted — both document infrastructure around Squad, not Squad itself; (2) issue-templates.md reframed to clarify "GitHub feature configured for Squad" not "Squad feature"; (3) reviewer-protocol.md Trust Levels section kept — documents user choice spectrum within Squad's existing review system. Litmus test pattern: if Squad doesn't ship the code/config, it's IRL content. Docs-test sync maintained. Pattern reinforced as reusable boundary review heuristic for future doc PRs. + +**Adoption tracking architecture — three-tier opt-in system:** `.squad/` is for team state only, not adoption data (boundary pattern). Move tracking to `.github/adoption/`. Never list individual repos without owner consent — aggregate metrics only until opt-in exists. Tier 1 (ship now) = aggregate monitoring. Tier 2 (design next) = opt-in registry in `.github/adoption/registry.json`. Tier 3 (launch later) = public showcase once ≥5 projects opt in. Monitoring infra (GitHub Action + script) is solid — keep it. Privacy-first architecture: code search results are public data, but individual listings require consent. + +**Remote Squad access — three-phase rollout:** Phase 1 (ship first): GitHub Discussions bot with `/squad` command. Workflow checks out repo → has full `.squad/` context → answers questions → posts reply. 1 day build, zero hosting, respects repo privacy automatically. Phase 2 (high value): GitHub Copilot Extension — fetches `.squad/` files via GitHub API, answers inline in any Copilot client (VS Code, CLI, mobile). Works truly remote, instant, no cold start. 1 week build. Phase 3 (enterprise): Slack/Teams bot for companies. Webhook + GitHub API fetch. 2 weeks build. Constraint: Squad needs `.squad/` state (team.md, decisions.md, histories, routing) to answer intelligently. Any remote solution must solve context access. GitHub Actions workflows solve this for free (checkout gives full state). Copilot Extension uses Contents API. Discussions wins for MVP because it's async (perfect for knowledge queries), persistent (answers are searchable), and zero infra. Proposal-first: write `docs/proposals/remote-squad-access.md` before building. + +### Content Triage Skill Codified (2026-03-10) +Created `.squad/skills/content-triage/SKILL.md` to codify the boundary heuristic from PR #331. Defines repeatable workflow for triaging external content (blog posts, sample repos, videos, talks) to determine what belongs in Squad's public docs vs IRL tracking. Key components: (1) "Squad Ships It" litmus test — if Squad doesn't ship the code/config, it's IRL content; (2) triage workflow triggered by `content-triage` label or external content reference in issue body; (3) output format with boundary analysis, sub-issues for PAO (doc extraction), and IRL reference entry for Scribe; (4) label convention (`content:blog`, `content:sample`, `content:video`, `content:talk`); (5) Ralph integration for routing to Flight, creating sub-issues, and notifying Scribe. Examples include Tamir blog analysis (PR #331), sample repo with ops patterns, and conference talk. Pattern prevents infrastructure docs from polluting Squad's public docs while ensuring community content accelerates adoption through proper extraction and referencing. + +📌 **Team update (2026-03-11T01:27:57Z):** Content triage skill finalized; "Squad Ships It" boundary heuristic codified into shared team decision (decisions.md). Remote Squad access phased rollout approved (Discussions bot → Copilot Extension → Chat bot). PR #331 boundary review pattern established as standard for all doc PRs. Triage workflow enables Flight to scale as community content accelerates. + +--- + +### Issue Triage — 6 Unlabeled Issues Routed (2026-03-20) + +Triaged and labeled 6 unlabeled issues using routing table: + +- **#485 (Agent Specification PRD)** → squad:flight + squad:procedures — Architecture decision (Flight) + formal spec structure (Procedures) +- **#481 (StorageProvider PRD)** → squad:control + squad:eecom — Type system abstraction (CONTROL) + runtime integration (EECOM) +- **#479 (history-shadow race condition)** → squad:eecom + squad:retro — Production data loss bug; mitigation through StorageProvider atomicity +- **#478 (Polish REPL)** → squad:vox + squad:pao — Shell UX readiness (VOX) + README documentation gate (PAO) +- **#477 (Code Quality Linting PRD)** → squad:fido — Monorepo async/promise quality, ESLint 9 PoC ready +- **#476 (Guide v0.4.1 update)** → squad:handbook + squad:pao — SDK patterns + documentation + +Key pattern: PRDs cluster around three architectural gaps (agent spec, state abstraction, quality tooling) + one production bug (#479). Guide update high community value. +### Ambient Personal Squad Architecture Review (#329 + #344) + +**Design validated:** The `flight-ambient-personal-squad.md` proposal is structurally sound. Key finding: `multi-squad.ts` already stores personal squad paths as direct dirs (`squads/{name}/`) with no nested `.squad/` subfolder — the "each team IS the squad root" convention is already the implementation, not a change needed. + +**Five gaps found in the design doc:** +1. No `resolvePersonalAgents()` function signature — added in implementation plan (T2). +2. Scenario 9 contradiction: personal agents wrote to project orchestration log, violating ghost protocol. Resolution: coordinator writes audit trail (project state), not the personal agent. +3. `--team-root` scope was undefined. Decision: additive CLI flag on `squad init`, backward compat with existing `config.json` teamRoot. +4. `squad personal init` was missing — bootstrapping path for first-time users. Added as T6 subcommand. +5. `SQUAD_NO_PERSONAL` env var was in Open Questions but absent from phases. Added to T1. + +**Architecture decision:** Need `ensureSquadPathTriple` in `resolution.ts` (T4) — personal agents write to a third root (personal squad dir). Without it, ghost protocol is advisory-only and not enforced by path guards in SDK. + +**Phasing:** Four PRs. MVP = PR #1 (SDK Foundation) + PR #3 (Governance). Users see ambient cast immediately; `squad personal` commands are quality-of-life on top. + +**Implementation plan written to:** `.squad/decisions/inbox/flight-329-344-implementation-plan.md` + +📌 **Team update (2026-03-24):** Ambient personal squad design reviewed and approved with 5 gaps identified and resolved. Implementation plan broken into 4 PRs across EECOM (SDK + CLI), Procedures (governance), and Sims (tests). MVP path = SDK foundation + governance updates. Phased to avoid one giant PR. + +### Session 2 Summary (2026-03-22) + +Wave 1 architecture work on #329/#344: validated 20KB personal squad design doc, identified and patched 5 gaps, authored 19-task implementation plan spanning 4 future PRs. Implementation not yet started — deferred to future session. EECOM assigned Phase 1–2 (SDK + CLI), Procedures assigned Phase 3 (governance), Sims assigned Phase 4 (tests). + +### Community PR Batch Review — July 2026 + +Five open community PRs reviewed: + +- **#524 (diberry)** — Astro docs improvements (sitemap, RSS, schema fields, ToC component, robots.txt). ✅ Merge-ready. Flag: `robots.txt` Sitemap URL points to `squad.dev` while `astro.config.mjs` still uses `bradygaster.github.io` — minor URL inconsistency to address. +- **#523 (diberry)** — Worktree-aware `detectSquadDir` + `resolveWorktreeMainCheckout` + init guard. ✅ Merge-ready. Directly addresses the worktree gap flagged in #525. Clean implementation; interactive TTY prompt with sensible default. +- **#522 (tamirdresher)** — Rate limiting/circuit breaker watch integration. 🔄 Still a full rewrite of watch.ts. Brady's CHANGES_REQUESTED (additive patch, not full file replacement) has NOT been addressed. Same structural concern remains. +- **#513 (tamirdresher)** — Cross-machine-coordination SKILL.md. 🔄 Wrong directory (`.squad/skills/` is team-state; generic library content belongs in `templates/skills/`). Personal use case examples (voice cloning, DevBox) should be generalized. Needs `docs/proposals/` entry per proposal-first policy. +- **#507 (JasonYeYuhe)** — Chinese README translation. 🔄 Needs a community-maintained freshness disclaimer before merging. Translation quality looks solid; the maintenance burden concern is the only gate. + +**Patterns noted:** +- Diberry (MSFT) is delivering consistent, architecturally-sound contributions — both PRs are merge-ready. +- Tamir's contributions are technically strong but need delivery discipline (full-rewrite vs. surgical patch, proposal-first for new primitives). +- Community translations are welcome but need a sustainability framing before merge. + +### Worktree Gap Triage — #525 (2025-07-18) + +Community contributor joniba filed #525 identifying that Squad has full worktree *detection* but zero worktree *creation* in the coordinator/spawn flow. Validated all 10 claims — analysis is accurate. The reading infrastructure (resolveSquad() worktree detection, .gitattributes merge=union, boundary tests) is ~95% complete. The gap: ralph-commands.ts hardcodes `git checkout -b` in all 3 platform adapters (lines 50/71/92), coordinator never creates worktrees before spawn, no WORKTREE_PATH in prompts, and issue-lifecycle.md is referenced in squad.agent.md but doesn't exist. + +**Decision:** P2 — important but not v1-blocking. Broke into 5 sub-issues: (1) doc fix for missing issue-lifecycle.md (quick win → Procedures), (2) worktree variant in ralph-commands.ts (EECOM), (3) coordinator pre-spawn logic (Procedures + EECOM), (4) post-merge cleanup (EECOM), (5) architecture decision on heuristic (Flight). Sub-issue #1 ships immediately; #2–5 queue post-Wave-1 alongside SubSquads work where parallel execution becomes a hard requirement. + +**Backlog priority recommendation:** Top 5 for v1 = #508 (Ambient Personal Squad), #498 (remove .squad/ from VCS), #485 (Agent Spec & Validation), #481 (Typed StorageProvider), #347 (shore up init --sdk). Quick wins: #525 doc fix, #347. Deprioritize: manual verification debt (#418–421), long-term exploratory. A2A (#332–336) stays shelved per existing decision. + +### Release Hardening Plan — Finalized (2026-07-22) + +Brady approved scope for remaining v0.9.1 incident hardening. Three issues to execute, three deferred into umbrella: + +**DO:** #564 (rewrite PUBLISH-README.md as living playbook — absorbs #558, #559, #560), #557 (CI lint rule rejecting non-workspace `npm publish` in workflow YAML), #562 (delete ghost workflow `publish-npm.yml` ID 250121956). + +**DEFERRED into #564:** #560 (pre-flight checklist → playbook section), #559 (fallback protocol → playbook section), #558 (422 race docs → playbook section). + +**Key findings:** +- GitHub REST API has NO "Delete a workflow" endpoint. Ghost workflows only disappear when all their runs are deleted (GitHub GC). Procedure: `gh api` to list+delete all runs for workflow ID 250121956, then wait for GC. +- The lint rule goes in `squad-ci.yml` as a `publish-policy` job: scans `.github/workflows/*.yml` for `npm publish` without `-w` flag. Blocks PR merge if violated. +- PUBLISH-README.md playbook has 11 sections covering pre-flight, CI publish, manual fallback, 422 race conditions, insider channel, workspace policy, post-publish verification, and version bumping. Replaces the stale v0.8.22 stub entirely. + +**Execution order:** #562 (Brady, manual API call) and #557 (FIDO/Procedures, CI change) run in parallel. #564 (Procedures+Surgeon, playbook) goes last so it can reference the lint rule. + +Decision written to `.squad/decisions/inbox/flight-release-hardening-plan.md`. + +### Issue Triage Session — 14 Untriaged Issues (2026-03-24) + +**Triaged 14 issues + 10 PRs:** 3 docs issues, 6 community feature proposals, 3 bugs, 2 questions. Key findings: + +**P0 Bug (immediate):** +- #590 (getPersonalSquadRoot) → squad:eecom — personal squad broken since v0.9.1, affects all `squad consult` on new repos + +**P1 Quick Wins:** +- #610 (broken docs link) → squad:pao — 5-minute fix, unblocks diberry PR #611 CI +- #591 (hiring wiring docs) → squad:procedures — matches PR #592 (joniba), high-quality wiring guide ready to merge + +**Community PRs (proposal-first enforcement):** +- Tamir PRs #602-607 (6 PRs) — high technical quality but missing proposal-first compliance. Need `docs/proposals/` entries before review. +- Joniba PR #592 — merge-ready, validates enforcement wiring gap +- Diberry PR #611 — blocked on #610 fix, then merge + +**P2 Maintenance:** +- #597 (upgrade CLI docs) → squad:pao + squad:network +- #588 (model list update) → squad:procedures +- #554 (broken external links) → squad:pao + +**Deferred/Questions:** +- #581 (ADO PRD) → P2, blocked until #341 SDK-first parity ships +- #589, #494 → community replies clarifying skill paths and model selection + +**Pattern:** Tamir is a high-output contributor (6 PRs in 2 weeks) but needs proposal-first discipline. Joniba and diberry deliver MSFT-level quality. + +Decision written to `.squad/decisions/inbox/flight-triage-session-plan.md`. diff --git a/.squad/agents/pao/history-archive-2026-08-19T13-11-34.130-07-00.md b/.squad/agents/pao/history-archive-2026-08-19T13-11-34.130-07-00.md new file mode 100644 index 000000000..8c8c85ed7 --- /dev/null +++ b/.squad/agents/pao/history-archive-2026-08-19T13-11-34.130-07-00.md @@ -0,0 +1,315 @@ +# PAO + +> Public Affairs Officer + +## Core Context + +Docs live in docs/ with blog/, concepts/, cookbook/, getting-started/, guide/, features/, scenarios/ sections. Blog tests use filesystem discovery (dynamic); other sections use hardcoded expected arrays. Microsoft Style Guide enforced: sentence-case headings, active voice, second person, present tense. Docs format: plain markdown, H1 title, experimental warning, "Try this" code blocks, overview, HR, H2 content sections. Scannability framework: paragraphs for narrative, bullets for scannable items, tables for comparisons. + +## Recent Learnings + +### Release Playbook Rewrite (#564, 2026-07-22) +Rewrote PUBLISH-README.md from v0.8.22 stub (58 lines) to living 232-line version-agnostic playbook with 11 sections: Overview, Pre-Flight Checklist, Publish via CI (recommended), workflow_dispatch fallback, Insider Channel, Workspace Publish Policy, Manual Local Publish, 422 Race Condition & npm Errors, Post-Publish Verification, Version Bump, Legacy Scripts. Pattern: living playbook absorbs multiple issues (#558, #559, #560) into unified decision tree. Microsoft Style Guide enforced; `` placeholder; all commands copy-pasteable. + +📌 **Team update (2026-03-24T06-release-hardening):** Release playbook rewrite (#564) completed. Absorbed issues #558, #559, #560 into unified decision tree. + +### JSDoc API Reference PRD (2026-03-24) +Full PRD at `docs/research/jsdoc-api-reference-prd.md`. Key decisions: TypeDoc + typedoc-plugin-markdown (not Starlight, not api-extractor) — zero migration, Markdown-first, Pagefind-compatible. Astro integration hook auto-runs TypeDoc on build. Output → `docs/src/content/docs/reference/api/`. JSDoc improvement priority: config/schema.ts (8%→100%), state/io/ @param/@return tags. Total effort: 13–18 hours. PRD structure: chosen path + tactical roadmap (not advisory — directive). + +### Community Engagement Wave (2026-03-24) +6 discussions closed as resolved (features shipped in v0.9.1: per-agent models #463/#402, local-only #324, CLI vs agent #299, human members #143, skills system #169). 8 discussions kept open with substantive replies. Pattern: feature-release timing + follow-up responses critical for community trust. **Teams MCP critical:** Office 365 Connectors retired Dec 2024 → Power Automate Workflows is successor. Purge all old connector references. + +## Historical Learnings Summary (condensed) + +- **Discussion triage pattern:** When you ship features, search discussions for matching feature-requests → respond + close proactively. Map new features to open discussions; respond with version + docs link; close as resolved; consolidate duplicates; convert bugs/roadmap items to issues. 43% closure rate on resolved items. +- **Docs-test sync:** When adding docs pages, update test assertions in docs-build.test.ts in the SAME commit. When rebasing doc PRs, main branch (already merged) takes priority. +- **Boundary review:** "Squad Ships It" litmus test — if Squad doesn't ship the code, it's IRL content. Platform features: clarify whose feature it is. Delete external infrastructure docs; reframe platform integration docs; keep Squad behavior/config docs. Pattern from PR #331. +- **Astro docs format:** Plain markdown, H1 title, experimental warning callout, "Try this" code blocks at top, overview paragraph, HR, then H2 sections. No Astro frontmatter. DOCS-TEST SYNC mandatory. +- **Scannability framework:** Paragraphs for narrative (3-4 sentences max). Bullets for scannable items. Tables for comparisons. If reader hunts for one item in a paragraph → convert to bullets/table. +- **npx purge:** `npm install -g @bradygaster/squad-cli` is only supported install path. Remove all user-facing `npx` references. Keep `npx` only for dev tools (changeset, vitest, astro, pagefind). Agency copilot example → `gh copilot`. +- **README slimming:** README cut from 512 to 331 lines. SDK deep-dive → compact pointer to docs site. README = discovery/orientation; docs site = full reference. +- **Docs catalog audit:** 15 orphaned pages (exist but not in navigation.ts). Stale content: whatsnew.md, insider-program.md. Duplicate/overlap pairs. Booster added automated version sync for whatsnew.md. Nav structure: zero dead links, all orphans reachable internally. +- **PR Trust Model:** Three levels: Full review (default), Selective review (personal projects), Self-managing (solo personal repos only). Self-managing ≠ unmonitored — use Ralph + Teams notifications. +- **JSDoc API Reference Research:** TypeDoc + typedoc-plugin-markdown. Squad SDK 60-80% JSDoc coverage. Research at `docs/research/jsdoc-api-reference-research.md`. Configuration templates, 4-phase roadmap, tool comparison matrix. +- **v0.9.0 blog post format:** YAML frontmatter (title/date/author/wave/tags/status/hero) → experimental warning → "What Shipped" (H2 sections + callout boxes) → "Quick Stats" → "Breaking Changes" → "Upgrading" → "What's Next". 200-400 words for infrastructure releases. EXPECTED_BLOG uses filesystem scan — no test changes needed. +- **PR #11 TypeDoc review (2026-03-24):** Generated docs require crosslinks from curated guides. When adding new docs section, ensure old curated page has a visible pointer to the new section. Blocking issues: missing sdk.md crosslink banner, navigation URL inconsistency (`reference/api/index` → `reference/api`). +- **Contributor recognition:** CONTRIBUTORS.md tracks team roster + community contributors. Each release includes recognition updates. Append PR counts, don't replace. +## Learnings + +### Discussion Triage Patterns (2026-03-23 Release Incident) +**Context:** v0.9.1 release completed; 15 open discussions analyzing whether community response patterns matched feature releases. + +**Pattern identified:** Feature releases without follow-up discussion closes = missed trust opportunity. When you ship features (personal squad, worktrees, economy mode, rate limiting), search discussions for matching feature-requests → respond + close proactively. This signals to community that you listen. + +**Triage workflow:** +1. Map new features to open discussions (which discussions are solved by this release?) +2. Respond: "This feature is now available in v0.9.1. See docs link." +3. Close as resolved +4. Consolidate: if discussion #463 is duplicate of #402, merge responses into #402, close #463 +5. Convert: if discussion reveals a bug or roadmap item, convert to issue with label (e.g., squad:eecom) +6. Keep: if discussion is feedback or edge case, keep open; respond substantively + +**For v0.9.1 release:** 4 closed, 1 consolidated, 2 converted to issue, 8 kept. Result: community sees responsiveness; discussions become productivity tool, not backlog. + +**Critical finding:** Teams MCP docs need urgent update — Office 365 Connectors deprecated Dec 2024. Docs must purge old connector references and document Power Automate Workflows path (new successor). + +### Chinese README Workflow (2026-03-23 Release Incident) +Community contributor (PR #572) provided Chinese README translation. Approved and merged as part of v0.9.1 release. Pattern: accept community translations; list contributors in CONTRIBUTORS.md; acknowledge in release notes. + +### Teams MCP Urgency Pattern (2026-03-23) +External tool integrations deprecate. Office 365 Connectors retired Dec 2024. Docs mentioning deprecated tools create support burden and user confusion. Action: audit all external tool integration docs for deprecation; update with successor guidance (Power Automate Workflows for Teams). + +### Blog Post Format +YAML frontmatter: title, date, author, wave, tags, status, hero. Body: experimental warning, What Shipped, Why This Matters, Quick Stats, What's Next. 200-400 words for infrastructure releases. No hype — explain value. + +### Boundary Review Heuristic +"Squad Ships It" litmus test: if Squad doesn't ship the code/config, it's IRL content. Platform features used alongside Squad: clarify whose feature it is. Squad behavior/config docs stay. External infrastructure docs (ralph-operations, proactive-communication) → IRL. + +### DOCS-TEST SYNC +When adding docs pages, update test assertions in docs-build.test.ts in the SAME commit. When rebasing doc PRs, main branch (already merged) takes priority. + +### Contributor Recognition +CONTRIBUTORS.md tracks team roster and community contributors. Each release includes recognition updates. Append PR counts, don't replace. + +### Skill Scope Documentation Pattern +Explicitly state what a skill produces and does NOT produce. Deterministic skills prevent agents from generating unnecessary code when templates exist. + +### Teams MCP Audit +External tool integrations require explicit "where to get it" guidance. Placeholder paths need clarification that users must provide actual MCP server implementations. + +### Cross-Org Authentication Docs +Problem/solution structure for multi-account auth: gh auth switch, Copilot instructions, Squad skill pattern. Cover credential helpers, EMU variations, common error messages. Cross-reference in troubleshooting and enterprise-platforms pages. + +### Roster & Contributor Recognition (v0.8.25) +Squad moved to Apollo 13/NASA Mission Control naming scheme (Flight, Procedures, EECOM, FIDO, PAO, CAPCOM, CONTROL, Surgeon, Booster, GNC, Network, RETRO, INCO, GUIDO, Telemetry, VOX, DSKY, Sims, Handbook). CONTRIBUTORS.md tracks both team roster and community contributors; contributor table entries grow with PRs (append PR counts rather than replace, maintaining attribution history). + +### Git Rebase for Doc Merges +When rebasing doc PRs with conflicts from other merged doc PRs, the main branch version (already merged) should generally take priority. For Node.js version references, maintain LTS terminology when present (e.g., `nvm install --lts` over specific version numbers like `nvm install 20`). Conflict resolution pattern: preserve new content from PR branch only where it doesn't duplicate or contradict already-merged changes. Use `git -c core.editor=true rebase --continue` to bypass interactive editor issues on Windows. + +### Astro Docs Format (v0.8.26) +Squad docs use plain markdown without Astro frontmatter. Structure: title (H1), experimental warning callout, "Try this" code blocks at top, overview paragraph, horizontal rule, then content sections with H2 headings. Microsoft Style Guide enforced: sentence-case headings, active voice, second person ("you"), present tense, no ampersands except in code/brand names. Features and scenarios directories added to test coverage in docs-build.test.ts. Reference implementations linked where available (e.g., ralph-watch.ps1 for operational patterns). + +### Proactive Communication Patterns (v0.8.26) +Two-way communication layer between Squad and work environment. Outbound: Teams webhook notifications (breaking, briefings, recaps, flashes) sent via Adaptive Cards — only when newsworthy. Inbound: WorkIQ/Playwright scanning of Teams channels and email → auto-create GitHub issues with teams-bridge label, anti-duplicate logic enforced. Loop: inbound creates issues → Ralph dispatches → agents work → outbound notifies results. Human stays informed on mobile. Prerequisites are enhancements, not requirements. + +📌 **Team update (2026-03-11T01:27:57Z):** Proactive communication patterns and PR trust levels (full/selective/self-managing spectrum) documented in decisions.md. Pattern rationale reinforced: Ralph 24/7 autonomous deployment requires awareness loop (Teams webhooks for outbound) and external work integration (WorkIQ scanning for inbound). Trust levels enable context-appropriate oversight without bottlenecking teams. + +### PR #487 Review & Merge — CLI Docs Expansion (2026-03-22) + +Reviewed and merged PR #487 (CLI documentation expansion + broken docs link fix). Improved CLI command reference coverage and fixed internal link validation. + +**Pattern identified:** Broken internal links hurt user navigation and SEO. Recommendations: (1) add link validation to docs build pipeline (crawl all internal references, report 404s), (2) make validation a CI gate (fail build on broken links), (3) maintain link checklist when refactoring docs structure. + +**Key learning:** Documentation maintenance requires systematic link validation. A single broken link creates friction for users following guides. Automated validation should be non-negotiable in CI/CD. + +### PR #482 Review & Merge — Pagefind Search Integration (2026-03-22) + +Reviewed and merged PR #482. Search functionality integrated into docs site for improved discoverability. + +### PR #11 Docs Quality Review — TypeDoc API Reference (2026-03-24) + +**Status:** REQUEST CHANGES (3 fixes required, 2 recommended) + +**Key findings:** +- **Research + PRD:** Excellent quality. Clear problem statement, realistic effort estimate, pragmatic tool choice (TypeDoc over Starlight/api-extractor). Scannability framework applied correctly (tables for audit data, bullets for findings, paragraphs for narrative). +- **Navigation strategy:** Collapsible `
` approach for 395-page API reference is sound UX. Sidebar nav plan well-structured with clear open questions about CI/CD safety. +- **Microsoft Style compliance:** Mostly strong; discovered 3 minor issues. + +**Issues found:** +1. **🔴 Blocking:** sdk.md crosslink banner missing. Users navigating from curated "SDK" guide have no callout to the auto-generated "API Reference". Add "See Also" link in sdk.md before "## Resolution" section. +2. **🔴 Blocking:** Navigation URL inconsistency. `navigation.ts` hardcodes `reference/api/index` when it should be `reference/api` — Astro resolves `/api/` to `/api/index` automatically. Simplify slug. +3. **🟡 Blocking:** Nav plan's "Open Questions" section asks about CI/CD fallback (generated JSON missing). Plan should either specify build order (`docs:api` before `docs build`) or provide fallback empty nav for fresh clones. +4. **🟡 Recommended:** 2–3 test descriptions need more specificity (e.g., "class page renders heading and content" → "class page renders method signatures and definition source"). +5. **🟡 Recommended:** Screenshot filenames don't align with skill convention. Use semantic names: `api-reference-landing`, `api-class-detail`, `api-function-detail`. + +**Pattern identified:** Generated documentation requires crosslinks from curated guides. When adding a new docs section (API reference, CLI reference, etc.), ensure the *old* curated page (SDK Guide) has a visible pointer to the new section. This prevents users from stopping at the curated version and missing the comprehensive auto-generated reference. + +**Effort to fix:** < 2 hours. All issues are surgical edits to existing content; no architectural changes needed. + +### PR #484 Review & Merge — Sample READMEs (2026-03-22) + +Reviewed and merged PR #484. Sample README templates added to improve consistency across documentation examples. + +### PR Trust Model Documentation (v0.8.26) +Three trust levels for PR management: (1) Full review (default, team repos) — human gate on every merge; (2) Selective review (personal projects with patterns) — human reviews only critical paths; (3) Self-managing (solo personal repos only) — Squad merges own PRs, human reviews retroactively. Added to reviewer-protocol.md as new section. Important: self-managing ≠ unmonitored; use Ralph work monitoring and Teams notifications for awareness. Decision matrix included for when to use each level. + +### Final Docs Review Pattern (v0.8.26) +Pre-PR quality reviews check: (1) Microsoft Style Guide compliance (sentence-case headings, active voice, no ampersands, present tense, second person); (2) Tone consistency (practical, developer-focused, no hype); (3) Technical accuracy (code examples, file paths, commands); (4) Cross-reference integrity (valid links between pages); (5) DOCS-TEST SYNC (test assertions match new pages); (6) Privacy directive compliance (no individual repos without consent). Fixed duplicate section heading in reviewer-protocol.md (merge artifact). All staged docs passed review and are ready to commit. + +### Squad vs IRL Boundary Review (v0.8.26) +Evaluated four docs pages from PR #331 (Tamir's blog analysis) against Squad-specificity criterion: does content document Squad features/patterns (belongs in Squad docs) or community implementation examples (belongs in Squad IRL)? Key distinction: Squad docs = "how the feature works + universal best practices" vs IRL = "how one person built an amazing setup." Results: ralph-operations.md borderline (deployment wrappers are external infrastructure, not Squad features — trim "outer loop" framing), issue-templates.md borderline (GitHub feature documented for Squad context, not Squad code — clarify scope), proactive-communication.md does not belong (community extension pattern using WorkIQ/Playwright, not built into Squad), reviewer-protocol.md trust levels section belongs (documents user choice spectrum within Squad's existing review system). Pattern: if Squad doesn't ship the code, it's IRL content; if it's a GitHub platform feature used alongside Squad, clarify that distinction; if it documents actual Squad behavior/configuration, it belongs. + +### Boundary Review Execution (v0.8.26) +Executed boundary review findings from PR #331: (1) Deleted ralph-operations.md (infrastructure around Squad, not Squad itself — moved to IRL); (2) Deleted proactive-communication.md (external tools/webhooks — moved to IRL); (3) Reframed issue-templates.md intro to clarify "GitHub feature configured for Squad" not "Squad feature"; (4) Updated EXPECTED_SCENARIOS in docs-build.test.ts to match remaining files. Pattern reinforced: boundary review = remove external infrastructure docs, reframe platform integration docs to clarify whose feature it is, keep Squad behavior/config docs. Changes staged for commit. + +### Cross-Org Authentication Docs (v0.8.26) +Created docs/src/content/docs/scenarios/cross-org-auth.md covering GitHub personal + Enterprise Managed Users (EMU) multi-account auth. Three solutions documented: (1) gh auth switch for manual account toggling; (2) Copilot instructions (.github/copilot-instructions.md) for account mapping documentation; (3) Squad skill pattern for auth error detection and recovery. Covered git credential helpers (per-host and per-org), EMU hostname variations (github.com vs dedicated instances), and common error messages (HTTP 401, authentication required). Added cross-references in troubleshooting.md (new section), enterprise-platforms.md (authentication section), and navigation.ts. Updated test/docs-build.test.ts with 'cross-org-auth' in EXPECTED_SCENARIOS. Pattern: Microsoft Style Guide (sentence-case), "Try this" prompts at top, problem/solution structure, practical examples over abstractions, links to related pages at bottom. + +### Scannability Framework (v0.8.25) +Format selection is a scannability decision, not style preference. Paragraphs for narrative/concepts (3-4 sentences max). Bullets for scannable items (features, options, non-sequential steps). Tables for comparisons or structured reference data (config, API params). Quotes/indents for callouts/warnings. Decision test: if reader hunts for one item in a paragraph, convert to bullets/table. This framework is now a hard rule in charter under SCANNABILITY REVIEW. + +### Docs Catalog Audit (2026) +Full audit of the Astro-based docs site. Key patterns and findings: + +**Orphaned pages (exist but not in navigation.ts):** 15 total — `get-started/choose-your-interface.md`, `guide/faq.md`, `guide/build-autonomous-agent.md`, `guide/github-auth-setup.md`, `features/built-in-roles.md`, `features/context-hygiene.md`, `features/cost-tracking.md`, `features/issue-templates.md`, `reference/vscode-troubleshooting.md`, and 6 root-level legacy files (`guide.md`, `sample-prompts.md`, `tips-and-tricks.md`, `tour-first-session.md`, `tour-github-issues.md`, `tour-gitlab-issues.md`). + +**Stale content:** `whatsnew.md` reports v0.8.2 as current; actual is v0.8.26+. `insider-program.md` uses deprecated `npx github:` install format and references old `.ai-team/` directory name throughout. + +**Duplicate/overlap pairs:** `choosing-your-path.md` (in nav) vs `choose-your-interface.md` (orphan, more complete); root-level `sample-prompts.md` vs `guide/sample-prompts.md`; root-level `tips-and-tricks.md` vs `guide/tips-and-tricks.md`; root-level `tour-first-session.md` vs `get-started/first-session.md`. + +**Content quality:** All actively-navved pages are well-written, follow Microsoft Style Guide, and use correct install commands. Format standards (H1, experimental callout, "Try this" block, HR, H2 sections) are inconsistently applied — some orphaned pages like `built-in-roles.md` and `cost-tracking.md` lack the standard header/callout pattern. + +**Structural issues:** `features/team-setup.md` has a duplicate `## How Init Works` heading (merge artifact). `features/streams.md` nav title is "Streams" but H1 is "Squad SubSquads" (mismatch). `guide/faq.md` is a high-value page completely invisible from the sidebar. `features/built-in-roles.md` is a comprehensive roles reference also invisible from nav. + +**Gap:** No dedicated FAQ entry point, no changelog page, cookbook section is thin (one page), no user-facing explanation of the NASA Mission Control naming scheme for agents. + +**Navigation:** Zero dead nav links (every nav slug has a matching file). All orphan pages are linked internally from other pages so they are reachable — but not browseable via sidebar. + +📌 **Team update (2026-03-22T12:46:00Z):** Booster implemented automated version sync for `whatsnew.md` (finding #1). Script reads `package.json` version, updates "Current Release" heading on every prebuild, with Vitest test gate. Heading now correct (v0.8.25+), will stay in sync automatically on all future builds. Finding #1 resolved. + +### JSDoc API Reference Research (2026-03-23) + +Completed research on generating JSDoc-based API reference documentation for Squad SDK. Key findings: + +**Current State:** Squad SDK has 60–80% JSDoc coverage across major modules (state: 81%, config: 8%). 136 TypeScript source files, no existing TypeDoc config. + +**Tool Recommendation:** **TypeDoc + typedoc-plugin-markdown** — no Starlight migration needed. Seamless integration with existing Astro 5 + Tailwind 4 + Pagefind. Markdown output drops directly into content collections. Auto-generates via Astro integration hook on `npm run build`. + +**Alternatives Evaluated:** +- ❌ Starlight migration: would break existing docs structure and custom branding +- ❌ api-extractor: overkill for open-source SDK; designed for strict monorepo contracts + +**Effort Estimate:** 5–6 hours (setup only) → 13–18 hours (setup + JSDoc improvements) → 15–22 hours (with CI/CD automation). + +**StorageProvider & State Module:** Phase 2 state layer is API-docs ready (81% coverage, well-structured types, clear interface contract). Gaps: add @param/@return tags to state/io functions. + +**URL Structure:** `/api/classes/squad-coordinator/`, `/api/interfaces/storage-provider/`, etc. Pagefind indexes automatically. + +**Deliverable:** Full research at `docs/research/jsdoc-api-reference-research.md` with configuration templates, implementation roadmap (4 phases), and tool comparison matrix. Decision summary at `.squad/decisions/inbox/pao-jsdoc-research.md`. + +### Issue Triage (2026-03-22T06:44:01Z) + +**Flight triaged 6 unlabeled issues and filed 1 new issue.** + +PAO assigned: +- **#488 (GitHub auth setup for project boards)** → squad:pao (documentation, newly filed) +- **#478 (Polish REPL)** → squad:vox + squad:pao (shell UX readiness + README documentation gate) +- **#476 (Guide v0.4.1 update)** → squad:handbook + squad:pao (SDK patterns + documentation) + +New issue #488 is documentation-focused; Fleet relabeled from squad:fido → squad:pao for proper domain ownership. + +📌 **Team update (2026-03-22T06:44:01Z):** Flight issued comprehensive triage. PAO owns GitHub auth docs (#488), REPL documentation gate (#478), and Guide v0.4.1 refresh (#476). High community value on Guide update. Ready to begin documentation work on next sprint. +### npx Purge + Agency Audit +Brady's distribution directive: `npm install -g @bradygaster/squad-cli` is the only supported install path. Remove ALL user-facing `npx @bradygaster/squad-cli` and `npx github:bradygaster/squad` references from docs. Replace with either `npm install -g` (for install steps) or `squad ` (for usage steps). Keep `npx` only for dev tools (changeset, vitest, astro, pagefind). Keep historical blog posts as-is. Migration.md "Before" column and CI/CD "OLD" examples are valid historical context — keep them. Insider program: `npm install -g @bradygaster/squad-cli@insider` and `squad upgrade` replace the old `npx github:bradygaster/squad#insider`. Agency audit: all "agency-agents" references in source files and docs are MIT attribution for the upstream open-source project — legally required, never touch them. The `agency copilot` example in cli-entry.ts help text was a competing-product reference — changed to `gh copilot`. + +### README Slimming + Upgrade Section (v0.8.x) +Brady directive: README was too long at 512 lines. Cut the SDK deep-dive block (custom tools, hook pipeline, Ralph API code) and replaced it with a compact pointer to the docs site. Added a dedicated "Upgrading" section (two-step: `npm install -g` then `squad upgrade`) after Quick Start. Final length: 331 lines. SDK internals live in `docs/src/content/docs/reference/sdk.md` and `tools-and-hooks.md`. The README is now discovery/orientation; the docs site is the full reference. + +### v0.9.0 Release Blog Post (2026-03-23) +Created `docs/src/content/blog/028-v090-whats-new.md` documenting Squad's biggest release: Personal Squad (ambient agent discovery + Ghost Protocol), Worktree Spawning (isolated branches per issue), Machine Capability Discovery (needs:* label routing), Cooperative Rate Limiting (predictive circuit breaker), Economy Mode (budget-aware model selection), Auto-Wired Telemetry, P0 upgrade fixes, and docs refresh. Blog format: frontmatter (title/date/author/wave/tags/status/hero) → experimental warning → "What Shipped" (10 features with H2 sections + callout boxes) → "Quick Stats" → "Breaking Changes" (none) → "Upgrading" → "What's Next". Messaging: clear, engaging, factual (no marketing fluff). Demonstrated: Personal Squad governance layer, worktree isolation, capability declaration, RAAS traffic-light pattern, economy fallback logic. Docs refresh section emphasized: README from 512→218 lines, dedicated upgrade guide, npx purged, Astro features, Teams MCP refresh, autonomous agents guide. Contributors: diberry (worktree tests + docs), wiisaacs (security review), community. No breaking changes — all additive opt-in features. Test discovery is dynamic (EXPECTED_BLOG uses filesystem scan), so new post auto-discovered; no test file changes needed. Pattern reinforced: each feature needs a story — if you can't explain it, it's not ready. Demos over descriptions (concrete code examples, YAML config blocks, Bash CLI examples). + +### Discussion Triage (2026-03-23) + +Analyzed 15 open discussions for response strategy: +- **4 close-as-resolved** (#143, #169 — features now shipped; #402, #299 — answered with docs links) +- **1 close-as-duplicate** (#463 → #402) +- **2 convert-to-issue** (#161 root-copilot-hijack → bug/UX track; #534 enterprise-features → ongoing roadmap signal) +- **8 keep-open** (ongoing feedback, feature signals, edge cases, follow-up potential) + +Key pattern: 15 discussions = 7 feature-request/feedback signals, 4 answered-by-feature-release, 4 documentation-clarity gaps. Community is engaged; v0.9.1 (per-agent models, skills system, human team members, watch mode) directly addressed 5+ discussions that were open for 2-4 weeks. Timing of releases + follow-up responses critical for community trust. + +**Documentation gaps identified:** +- #440 (branch naming convention change) — needs migration guide in upgrade docs +- #306 (multi-root workspaces) → future feature; docs should clarify current limitation +- #140 (Teams MCP + Office 365 Connectors retirement) → docs refresh needed; Power Automate Workflows is the new path +- #401 (mobile/remote control) → feature exploration, keep on radar +- #161 (Coordinator hijacking) → document workarounds, prioritize UX fix for v1.0 + +Teams MCP critical update: Office 365 Connectors retired Dec 2024 → Power Automate Workflows is successor. Docs mention of old Connectors should be purged; Teams webhook examples should link to Power Automate Workflow guide. + +### Community Engagement Wave (2026-03-24) + +**6 discussions closed as resolved:** +- #463, #402 (per-agent model selection — shipped v0.9.1) +- #324 (local-only operation without GitHub integration) +- #299 (CLI vs Copilot agent — both viable) +- #143 (Human team members now first-class feature) +- #169 (Skills system shipped as core infrastructure) + +**8 discussions kept open with substantive replies:** +- #534 (enterprise features) — asked clarifying questions on scope +- #499 (Brady's v1.0 announcement) — explained `.squad/` regenerability plan +- #440 (branch naming change) — acknowledged disruption, offered migration guidance +- #401 (mobile/async control) — acknowledged use case, roadmap signal +- #376 (best practices) — provided triage and routing patterns +- #306 (multi-root support) — acknowledged limitation, kept open for feedback +- #95 (casting system) — explained mature re-casting flow +- #140 (Teams MCP) — critical guidance on Office 365 Connectors retirement → Power Automate Workflows + +**Pattern observed:** Feature-release timing + follow-up responses critical for community trust. v0.9.1 directly addressed 5+ discussions (models, skills, human members) that were open 2-4 weeks. Community triage now operational: 14 discussions reviewed, 6 closed, 8 kept active = 43% closure rate on resolved items. + +**Key insight:** Retirement of Microsoft Office 365 Connectors (Dec 2024) caught users mid-setup. Proactive notification of Teams Workflows alternative + Power Automate guidance essential for Teams MCP users. + +### Release Playbook Rewrite (#564, 2026-07-22) + +**Task:** Rewrite PUBLISH-README.md from a v0.8.22 version-specific stub (58 lines) into a living, version-agnostic release playbook. + +**Outcome:** 232-line playbook replacing entirely with 11 sections per Flight's spec: +1. Overview — two publish channels, package order (SDK → CLI) +2. Pre-Flight Checklist — runnable checklist with `grep`/`npm` commands +3. Publish via CI (Recommended Path) — GitHub Release workflow +4. Publish via workflow_dispatch — manual trigger fallback +5. Insider Channel — insider branch + `@insider` tag for testing +6. Workspace Publish Policy — reference to CI lint rule #557 (enforces `-w` flag) +7. Manual Local Publish — emergency fallback with step-by-step commands +8. 422 Race Condition & npm Errors — v0.9.1 incident + troubleshooting +9. Post-Publish Verification — `npm view` + npx cold-install test +10. Version Bump After Publish — preview version increment pattern +11. Legacy Publish Scripts — deprecation notice for PowerShell scripts + +**Key decisions:** +- Microsoft Style Guide enforced: sentence-case headings, active voice, "you" not "we", present tense +- Version-agnostic: `` placeholder, no hardcoded version numbers +- Scannability: checklist format, code blocks (bash not PowerShell for portability), tables for error reference +- Accuracy: pulled from actual workflows (`squad-npm-publish.yml`, `squad-insider-publish.yml`) — preflight job, smoke test, publish stages, registry propagation retry logic (5× 15-second intervals) +- Runnable: all commands copy-pasteable (e.g., `npm -w packages/squad-sdk pack --dry-run`) + +**Pattern:** Living playbook absorbs three related issues (#558 race conditions, #559 manual publish, #560 pre-flight checklist) into unified reference. No separate documents; all under one decision tree: try CI first, use manual only if CI broken. Workspace publish policy section references CI lint rule #557 (being added in parallel by FIDO); both docs + lint create enforcement + education. + +**Commit:** `docs: rewrite PUBLISH-README.md as release playbook (#564)` on squad/release-hardening branch. + +📌 **Team update (2026-03-24T06-release-hardening):** Release playbook rewrite (#564) completed. PUBLISH-README.md transformed from v0.8.22 stub to living 232-line playbook with 11 sections: Overview, Pre-Flight Checklist, Publish via CI (recommended), Publish via workflow_dispatch, Insider Channel, Workspace Publish Policy, Manual Local Publish (emergency fallback), 422 Race Condition & npm Errors, Post-Publish Verification, Version Bump After Publish, Legacy Publish Scripts. Absorbed issues #558, #559, #560 into unified decision tree. Microsoft Style Guide enforced; version-agnostic; all commands runnable. Scannability: checklist format, bash code blocks, error reference table. Committed to squad/release-hardening. +### JSDoc API Reference PRD (2026-03-24) + +Completed full PRD based on research findings. **Document:** `docs/research/jsdoc-api-reference-prd.md`. + +**Structure (8 major sections):** +1. Problem Statement — 5 concrete gaps (no dedicated API ref, uneven JSDoc coverage, discoverability, StorageProvider docs lag, Pagefind misses API symbols) +2. Goals & Success Metrics — 4 primary goals, 8 measurable targets (100% JSDoc coverage, 50+ auto-documented symbols, searchable API) +3. Key User Scenarios — 4 personas (SDK consumer, contributor, agent author, evaluator) with today vs future workflows +4. Scope — clear in/out boundaries (TypeDoc + JSDoc improvements in; CLI ref gen, Starlight migration, multi-version docs out) +5. Approach — architecture (TypeDoc in Astro hook), config template (typedoc.json), output/URL structure, build integration code, JSDoc improvement plan with effort table +6. Implementation Phases — 4 phases: Phase 0 (setup/PoC, 1–2 days), Phase 1 (JSDoc audit, 5–6 hrs), Phase 2 (integration/nav, 3–4 hrs), Phase 3 (CI/CD optional, 2–4 hrs) +7. Risks & Mitigations — 7 risks (TypeDoc breaks on changes, stale markdown, link validation strictness, Pagefind misses, config maintenance, build perf, breaking changes) with specific mitigations +8. Architecture Review section — 4 items for CONTROL to review (TypeScript export strategy, TypeDoc config, JSDoc standards, stability commitments) + +**Key decisions baked into PRD:** +- TypeDoc + typedoc-plugin-markdown (not Starlight, not api-extractor) — zero migration, Markdown-first, Pagefind-compatible +- Astro integration hook auto-runs TypeDoc on build (single step: `npm run build`) +- Generated output goes to docs/src/content/docs/reference/api/ (one file per symbol) +- JSDoc improvement priority: config/schema.ts (8% → 100%), state/io/ functions (@param/@return tags), StorageProvider interface audit +- Total effort: 13–18 hours (8–12 JSDoc + 5–6 setup) + +**Style & Tone:** +- Written for Flight-level review/approval (actionable, opinionated, specific) +- Includes code examples (typedoc.json, Astro hook, JSDoc template) +- References research doc for detailed findings +- PRD as decision/commitment document — not advisory, but directive + +**Learnings:** +- PRD structure differs from research (research = exploratory findings/options; PRD = chosen path + tactical roadmap) +- Recommendation section in PRD serves as binding decision (TypeDoc chosen, rationale locked in) +- Architecture Review section ensures TypeScript team reviews export strategy and JSDoc standards early — prevents rework later +- Four-phase approach breaks large effort into digestible increments (Phase 0 validation before JSDoc audit helps mitigate risk of TypeDoc setup failing) + +**Decision:** PRD approved for handoff to implementation team. Ready for execution on next sprint. diff --git a/.squad/agents/procedures/history-archive-2026-08-19T13-11-34.130-07-00.md b/.squad/agents/procedures/history-archive-2026-08-19T13-11-34.130-07-00.md new file mode 100644 index 000000000..4f28c82ee --- /dev/null +++ b/.squad/agents/procedures/history-archive-2026-08-19T13-11-34.130-07-00.md @@ -0,0 +1,231 @@ +# Procedures + +> Standard Operating Procedures & Spec Writer + +## Learnings + +### Issue Triage (2026-03-22T06:44:01Z) + +**Flight triaged 6 unlabeled issues and filed 1 new issue.** + +Procedures assigned: +- **#485 (Agent Specification PRD)** → squad:flight + squad:procedures (architecture decision + formal spec structure) + +Pattern: Agent specification gap identified. Procedures owns formal spec structure and documentation; Flight owns architecture decisions. + +📌 **Team update (2026-03-26T06:41:00Z — Crash Recovery Execution & Model Catalog Merge):** Procedures executed Round 2 PR merge action: rebased PR #619 (model catalog refresh, issue #588) onto dev branch from main, resolved 3 merge conflicts, and successfully merged. Model catalog now current: default model bumped to `claude-sonnet-4.6` (latest standard-tier Claude), specialist bumped to `gpt-5.3-codex` (latest code-writing specialist), fallback chains restructured to include new models (`gpt-5.4`, `gpt-5.4-mini`) and removed dead models (`claude-opus-4.6-fast`). All 6 original merge-plan PRs (#620, #627, #624, #611, #617, #619) now ✅ complete. Dev branch green (5,038 tests). Decision inbox merged to decisions.md and deleted. Next: Ready for follow-on feature PRs. + +📌 **Team update (2026-03-22T06:44:01Z):** Flight issued comprehensive triage. Procedures owns Agent Specification PRD structure (#485). Architecture decisions from Flight. Coordinate on formal spec format and standard structure for future agent definitions. + +## Historical Learnings Summary (condensed 2026-03-10 → 2026-04-17) + +- **Deterministic skill pattern (2026-03-10):** Skills must have explicit SCOPE (what they produce/don't) and AGENT WORKFLOW (deterministic steps with STOP condition). Same input → same output, every time. +- **Self-contained skills (2026-03-15):** Resources (scripts, examples, configs) live WITH the skill directory, not in separate template dirs. Agents copy resources from the skill; no manual steps. +- **Three governance policies (2026-03-15):** Agent Error Lockout (2 errors → reassign), Product Isolation Rule (tests/CI/code never depend on squad names), Peer Quality Check (run tests before finishing). Applied to all 19 charters. +- **Team-wide reskill (2026-03-16):** 17.4% size reduction — NEVER/ALWAYS sections compress to single-paragraph summaries; essential workflow details stay verbose. +- **Economy mode skill (2026-03-22):** Layer 3 modifier only — never downgrades Layers 0-2 (user intent). `💰` indicator in spawn acknowledgments. Session phrase, persistent config, or CLI flag activation. +- **Personal squad governance (2026-03-22):** `CONSULT_MODE: true` as spawn signal. Governance changes go to `decisions/inbox/` for Flight review — don't edit squad.agent.md directly. +- **Spawn template `name` fix (2025-07):** Every `task` tool spawn MUST include `name` set to agent's lowercase cast name. Without it, platform defaults to generic slugs. +- **Model catalog refresh (2025-07 / 2026-03-25):** Model catalogs drift. Search ALL model name strings when refreshing — not just the catalog list. Sync via `sync-templates.mjs` to all 5 copies. +- **VS Code routing investigation (2026-03-25):** CLI-centric enforcement language causes coordinator to work inline in VS Code. Fix: platform-neutral dispatch language + reinforcement at prompt bottom. +- **VS Code routing fix (2026-07):** Fix 1 + Fix 2 shipped. CRITICAL RULE rewritten to dispatcher-identity framing ("DISPATCHER, not a DOER") with dispatch mechanism table. Routing Enforcement Reminder added as final section. Remaining P1 fixes (template renaming, prompt slimming) deferred. +- **PR #619 rebase (2026-07):** When a PR has accumulated dev merge commits, use `git rebase --onto dev ` to cherry-pick only relevant commits. +- **Trim copilot-instructions.md (#999, 2026-04-17):** 1300w/9KB → 397w/3KB. Extracted Protected Files to skill, consolidated Git Safety, removed duplication. Pattern: main instructions = routing/workflow; skills = domain-specific reference (lazy-loaded on demand). +# Procedures — Project History + +> Learnings, patterns, and context for the Prompt Engineer. + +## Learnings + +📌 **Team update (2026-03-22T09-35Z — Wave 1):** Economy mode governance proposal and personal squad consult-mode governance proposal authored for squad.agent.md — both DRAFT, awaiting Flight review before merging. Economy mode adds Layer 3 table + spawn convention (`💰 economy`) + model catalog audit. Personal squad adds consult mode detection, path reference table, spawn guidance. Persistent model preference (Layer 0) documented. Proposed new skill: `.squad/skills/consult-mode/SKILL.md` (post-approval). Deterministic skill pattern proven effective. PR #503 open with skills module. Next: Flight review → merge governance to squad.agent.md. No blocking issues. + +### 2026-03-10: Deterministic skill pattern + +**Problem:** Skills were too loose. The distributed-mesh skill was tested in a real project (mesh-demo), and agents generated 76 lines of validator code, 5 test files with 43 tests, regenerated sync scripts that should have been copied from templates, and left decision files empty. The skill document let agents interpret intent instead of following explicit steps. + +**Solution:** Rewrite skills to be fully deterministic: + +1. **SCOPE section** (right after frontmatter, before Context) + - ✅ THIS SKILL PRODUCES — exact list of files/artifacts + - ❌ THIS SKILL DOES NOT PRODUCE — explicit negative list to prevent scope creep + +2. **AGENT WORKFLOW section** — Step-by-step deterministic instructions + - ASK: exact questions to ask the user + - GENERATE: exactly which files to create, with schemas + - WRITE: exactly which decision entry to write, with template + - TELL: exact message to output to user + - STOP: explicit stopping condition, with negative list of what NOT to do + +3. **Fix ambiguous language:** + - "do the task" → clarify this means "the agent's normal work" not "build something for the skill" + - "Agent adds the field" → clarify this describes what a consuming agent does with data it READ + - Phase descriptions → note that phases are project-level decisions, not auto-advanced + +4. **Decision template** — inline markdown showing exactly what to write + +5. **Anti-patterns for code generation** — explicit list of things NOT to build + +**Pattern for other skills:** All skills should have SCOPE (what it produces, what it doesn't) and AGENT WORKFLOW (deterministic steps with STOP condition). Same input → same output, every time. Zero ambiguity. + +📌 Team update (2026-03-14T22-01-14Z): Distributed mesh integrated with deterministic skill pattern — decided by Procedures, PAO, Flight, Network + +### 2026-03-15: Self-contained skills pattern (agent-skills spec) + +**Problem:** The distributed-mesh skill had a manual gap — Step 4 told the user to copy sync scripts from templates/mesh/ manually. This violated the GitHub agent-skills spec, which says: "add scripts, examples or other resources to your skill's directory. The skill instructions should tell Copilot when, and how, to use these resources." + +**Solution:** Skills are self-contained bundles. Resources live WITH the skill, not in separate template directories: + +1. **Bundle resources IN the skill directory:** Copy `sync-mesh.sh`, `sync-mesh.ps1`, and `mesh.json.example` into `.squad/skills/distributed-mesh/` +2. **Update SKILL.md workflow:** + - Step 2: Reference `mesh.json.example` from THIS skill's directory + - Step 3: COPY sync scripts from THIS skill's directory to project root (agent does it, not user) + - Step 4: RUN `--init` if Zone 2 state repo specified (agent does it, not user) +3. **Update SCOPE section:** Clarify the skill PRODUCES the copied scripts (bundled resources ≠ generated code) +4. **Replicate to templates:** Copy entire skill directory to `templates/skills/`, `packages/squad-cli/templates/skills/`, `packages/squad-sdk/templates/skills/` + +**Pattern for all skills:** Skills are self-contained. Scripts, examples, configs, and resources travel WITH the skill. The agent reads SKILL.md, sees "copy X from this directory," and does it. Zero manual steps. + +### 2026-03-15: Three new governance policies added to agent system + +**Task:** Brady directive — implement three new policies across the agent system: + +1. **Agent Error Lockout** — Added to squad.agent.md. After 2 cumulative errors (build/test failures or reviewer rejection) on the same task, agent is locked out for that task only. Different agent takes over. Coordinator tracks and enforces; Scribe logs lockout events. + +2. **Product Isolation Rule** — Added to every charter and squad.agent.md Constraints. Tests, CI, and product code must NEVER depend on specific agent names from any squad. "Our squad" must not impact "the squad." Use generic/parameterized values (e.g., "test-agent-1") instead of real agent names (Flight, EECOM, FIDO). + +3. **Peer Quality Check** — Added to every charter. Before finishing work, agents must verify their changes don't break existing tests. Run test suite for files touched. Update history.md when learning from mistakes. + +**Implementation:** Updated `.github/agents/squad.agent.md` (new section + constraint) and all 19 active agent charters in `.squad/agents/*/charter.md`. + +**Pattern:** Policies added as subsections under "How I Work" in charters to ensure they're loaded with agent context. Coordinator-level policies live in squad.agent.md with explicit enforcement instructions. + +### 2026-03-16: Team-wide reskill — 17.4% reduction + +**Context:** Routine maintenance reskill, one day after previous reskill (2026-03-15). Last reskill brought the system from 117.4KB to 51.7KB. This pass focused on remaining oversized charters. + +**Work done:** +- **Scribe (2143→1557):** Compressed workflow steps, kept essential commit instructions +- **Handbook (1807→1529):** Removed repetitive LLM-FIRST DOCS emphasis +- **FIDO (1715→1370):** Consolidated verbose NEVER/ALWAYS sections +- **Booster (1583→1368):** Same NEVER/ALWAYS compression pattern + +**Results:** 26,721→17,088 bytes (charters), 28,602→28,602 bytes (histories), total 55,323→45,690 bytes. 9,633 bytes saved (17.4% reduction). All charters now ≤1.5KB. + +**Skill extraction:** No new patterns extracted. CastingEngine integration work (from EECOM March 15) is still evolving — not yet mature enough for skill template. Histories all <12KB, no compression needed. + +**Pattern:** NEVER/ALWAYS sections in charters compress well — fold bullet lists into single-paragraph summaries. Essential workflow details (Scribe's commit steps) should stay verbose. + +### 2026-03-22: Economy mode skill and personal squad governance (#500, #344) + +**Task:** Two governance tasks — economy mode skill design and personal squad coordinator awareness. + +**Economy mode (SKILL.md):** +- Created `.squad/skills/economy-mode/SKILL.md` as a Layer 3 modifier, not a new resolution layer +- Key design decision: economy mode ONLY affects Layer 3 auto-selection — Layer 0/1/2 (user intent) always wins +- `💰` indicator in spawn acknowledgments keeps it transparent +- Activation via session phrase, persistent config (`economyMode: true` in config.json), or CLI flag +- Architecture trips shift from opus → sonnet; code tasks shift from sonnet → gpt-4.1/gpt-5-mini +- Confidence: `low` — first implementation, not yet validated + +**Personal squad governance (proposals):** +- Gap analysis: coordinator has no consult mode awareness despite full SDK implementation +- Five gaps identified: Init Mode missing personal squad resolution, no consult mode detection, TEAM_ROOT has no personal-squad semantics, charter templates lack consult-mode patterns, no consult-mode skill +- Proposed `CONSULT_MODE: true` as spawn prompt signal, `🧳 consult` in acknowledgments +- Proposed new consult-mode skill (after governance approval — skill after governance, not before) + +**Governance workflow pattern:** When proposals touch squad.agent.md (governance territory), write to `decisions/inbox/` for Flight review. Don't directly edit squad.agent.md — Flight reviews governance changes. + +**Catalog audit finding:** `claude-sonnet-4.6`, `gpt-5.4`, `gpt-5.3-codex` appear in model-selection SKILL.md fallback chains but are absent from squad.agent.md's "Valid models" catalog. Documented in economy-mode governance proposal for Flight to address. + +### Session 2 Summary (2026-03-22) + +Wave 1 governance work on #500 and #344: authored economy-mode skill (`SKILL.md`), economy-mode governance proposal, and personal-squad governance proposal. Caught `claude-sonnet-4.6` missing from valid models catalog. PR #503 (`squad/500-344-governance`) merged to dev. + +### 2025-07: Spawn template `name` parameter fix (#577) + +**Problem:** Agent cast names weren't displayed during work — the tasks panel showed generic slugs like "general-purpose-task" instead of the cast name. Root cause: spawn templates in `squad.agent.md` specified `description` but NOT the `name` parameter for the `task` tool. The `name` parameter generates the human-readable agent ID shown in the tasks panel. + +**Fix:** Added `name: "{name}"` (lowercase cast name) to all spawn templates in `.squad-templates/squad.agent.md`: +- Lightweight Spawn Template +- Model-passing example +- Main full spawn template ("Template for any agent") +- Scribe spawn template (hardcoded `name: "scribe"`) + +Also updated: examples section (showing `name` + `description` pairs), anti-pattern #4 (now covers both `name` and `description`), and Constraints section (requiring `name` on every spawn). + +**Pattern:** Every `task` tool spawn MUST include `name` set to the agent's lowercase cast name. Without it, the platform defaults to generic slugs. The `description` parameter is for the human-readable summary; `name` is for the agent ID. + +📌 **Team update (2026-03-23T23:15Z):** Orchestration complete. Agent name display refactor shipped: spawn templates updated with mandatory `name` parameter across all 4 template variants. VOX and FIDO coordinated on parser extraction and cascading pattern strategies. All decisions merged to decisions.md. Canonical source: `.squad-templates/squad.agent.md` (all derived copies secondary). + +📌 **Team update (2026-03-25T18:11Z):** Model catalog updated to current platform offerings — removed 2 stale models (claude-opus-4.6-fast, gpt-5), added 5 new models (claude-sonnet-4.6, claude-opus-4.6-1m, gpt-5.4, gpt-5.3-codex, gpt-5.4-mini), bumped defaults (code: claude-sonnet-4.6, specialist: gpt-5.3-codex), restructured fallbacks. All 5 squad.agent.md template copies synchronized. Merged in #588. + +### 2025-07: Model catalog refresh (#588) + +**Problem:** The valid models catalog, fallback chains, role-to-model mappings, and default model references in `squad.agent.md` were stale — missing `claude-sonnet-4.6`, `gpt-5.4`, `gpt-5.3-codex`, `gpt-5.4-mini`, `claude-opus-4.6-1m` and still referencing removed models `claude-opus-4.6-fast` and standalone `gpt-5`. + +**Fix:** Full catalog refresh across all model-referencing sections: +- Catalog: added 5 new models, removed 2 stale ones +- Defaults: code-writing tasks bumped to `claude-sonnet-4.6` (newest standard); code specialist bumped to `gpt-5.3-codex` +- Fallback chains: restructured with new models in sensible positions (e.g., `gpt-5.4-mini` in fast tier, `gpt-5.4` in standard) +- All 5 copies synced via `sync-templates.mjs` + +**Pattern:** Model catalogs drift. When the platform adds/removes models, every section referencing models needs updating — not just the catalog list. Search for all model name strings before considering the refresh complete. +### 2026-03-25: VS Code routing enforcement investigation (#613) + +**Problem:** In VS Code, the coordinator reads routing rules but doesn't enforce them — continues working inline instead of dispatching via `runSubagent`. Andreas (andikrueger) reproduced and the agent itself admitted it violated the rules. + +**Root cause (dominant):** CLI-centric enforcement language. The CRITICAL RULE says "MUST use the `task` tool" — but in VS Code the dispatch tool is `runSubagent`. When `task` isn't available, the coordinator falls through Platform Detection's "Fallback mode" (work inline) instead of using `runSubagent`. The VS Code adaptations section is buried 360 lines below the CRITICAL RULE and reads as optional, not mandatory. + +**Amplifying factors:** +1. Prompt saturation: 950 lines / 80KB. Routing constraint competes with 900+ lines of governance, lifecycle, and reference material. Core dispatch loop is ~200 lines; rest is noise. +2. Template duplication: CLI 1.0.11 discovers all `*.agent.md` from cwd to git root. Squad has 5 copies — only `.github/agents/squad.agent.md` should be discoverable. + +**Proposed fixes (5 total, prioritized):** +- P0: Rewrite enforcement language to be platform-neutral ("dispatch tool" not "`task` tool") +- P0: Add routing reinforcement at bottom of prompt (LLMs weight start/end more than middle) +- P1: Rename template copies to `.agent.md.template` to prevent CLI discovery +- P1: Extract ~350 lines to lazy-loaded reference files (worktree, Ralph, casting, MCP) +- P1: Move VS Code dispatch block immediately after CRITICAL RULE + +**Key pattern learned:** Enforcement language must name ALL dispatch mechanisms, not just the CLI one. Platform-specific instructions buried deep in a long prompt get lost — they need to be co-located with the constraint they modify. LLM attention patterns favor prompt boundaries (top/bottom) over the middle. + +**Proposal filed:** `.squad/decisions/inbox/procedures-vscode-routing-fix.md` + +### 2026-07: VS Code routing enforcement — Fix 1 + Fix 2 shipped (#613) + +**Implemented** P0 fixes from the VS Code routing proposal: + +- **Fix 1 (Platform-Neutral Enforcement):** Rewrote CRITICAL RULE from CLI-specific "`task` tool" language to dispatcher-identity framing ("You are a DISPATCHER, not a DOER") with explicit dispatch mechanism table (CLI → `task`, VS Code → `runSubagent`, fallback → inline as last resort). Updated all 7 enforcement-context references throughout squad.agent.md: anti-patterns #1/#2/#3, constraints block, and spawn template header. + +- **Fix 2 (Top-and-Bottom Reinforcement):** Added `## ⚠️ Routing Enforcement Reminder` as final section, exploiting LLM prompt-boundary attention bias. Reinforces dispatcher identity at both top and bottom of the prompt. + +**Branch:** `squad/613-vscode-routing-enforcement` — canonical source edited, synced to all 5 copies via `scripts/sync-templates.mjs`, build verified clean. + +**Remaining P1 fixes** (template renaming, prompt slimming, VS Code block relocation) deferred to separate PRs per the proposal's ship order. + +### 2026-07: PR #619 rebase and merge — model catalog final sync + +**Problem:** PR #619 (model catalog update, #588) was the last of 6 PRs in the pre-crash triage merge plan. It had accumulated old dev merge commits and was behind after PRs #620, #627, #624, #611, and #617 merged first. Template renames from #624 (`.agent.md` → `.agent.md.template`) changed which files needed updating. + +**Fix:** Used targeted `git rebase --onto dev ` to replay only the 2 actual PR commits (skipping accumulated dev merge noise). Rebase applied cleanly — one commit landed, one was auto-dropped as already upstream. After rebase, only `packages/squad-sdk/templates/squad.agent.md.template` and `templates/squad.agent.md.template` needed changes since the canonical and other copies already had the model updates from earlier merges. + +**Pattern:** When a PR branch has accumulated merge commits from dev, use `git rebase --onto dev ` to cherry-pick only the relevant commits. This avoids conflict noise from old merge commits that are already in dev. Also: after template renames, the sync script may overwrite version stamps in the canonical file — revert those before pushing. + +### 2026-04-17: Trim copilot-instructions.md (#999) + +**Task:** Reduce `.github/copilot-instructions.md` from ~1,300 words / 9KB to ≤750 words / ≤4KB to reduce attention dilution for the Copilot coding agent. + +**Key decisions:** +- Extracted Protected Files (file list, rules, SDK/CLI boundary, anti-patterns) to `.copilot/skills/protected-files/SKILL.md` — replaced with 2-sentence pointer +- Consolidated Git Safety from 4 sub-sections (Staging, Pushing, Pre-Push Checklist, Branch Contamination Prevention) into a single 7-item flat list; resolved contradictory `git fetch upstream` vs `git fetch origin` (kept `origin`) +- Compacted Changeset Requirement from 7 lines + code block to 2 sentences +- Reordered: Team Context, Capability Self-Check, Branch Naming now appear before Git Safety (essential workflow first, safety rules second) +- Removed duplication with `.squad/copilot-instructions.md` (5 sections were verbatim copies; kept compact versions since both files load) +- Sweeping Refactor Rules condensed from 5-step list to 2-sentence pointer + +**Result:** 397 words / 3KB — well within target. PR #1002. + +**Files modified:** `.github/copilot-instructions.md`, `.copilot/skills/protected-files/SKILL.md` (new). + +**Pattern:** When trimming agent instructions, extract domain-specific reference content to skills (lazy-loaded on demand) and keep the main instructions file as a routing/workflow document. Skills are the right abstraction for "read this when you touch X" — they don't consume tokens until needed. + diff --git a/.squad/decisions.md b/.squad/decisions.md index 91fd48fa3..33dbe720a 100644 --- a/.squad/decisions.md +++ b/.squad/decisions.md @@ -105,8 +105,7 @@ Three factors combine to create the VS Code routing failure. Ranked by dominance #### 1. 🔴 CLI-Centric Enforcement Language (DOMINANT) -The routing constraint is expressed exclusively in CLI terms. The CRITICAL RULE references ask tool only. When the coordinator reads this in VS Code, where the tool is -unSubagent, it doesn't reliably make the substitution. It falls through to Platform Detection's Fallback mode: 'work inline.' This enforcement language creates a logical gap. +The routing constraint is expressed exclusively in CLI terms. The CRITICAL RULE references `task` tool only. When the coordinator reads this in VS Code, where the tool is `runSubagent`, it doesn't reliably make the substitution. It falls through to Platform Detection's Fallback mode: 'work inline.' This enforcement language creates a logical gap. #### 2. 🟡 Prompt Saturation (AMPLIFYING) @@ -120,8 +119,7 @@ CLI 1.0.11 discovers all \*.agent.md\ files from cwd to git root. Squad has 5 co **Fix 1: Platform-Neutral Enforcement Language (P0)** - Rewrite CRITICAL RULE to be platform-neutral: 'You are a DISPATCHER, not a DOER. Every task that needs domain expertise MUST be dispatched to a specialist agent.' -- List dispatch mechanisms: CLI (\ ask\ tool), VS Code (\ -unSubagent\ tool), or fallback (work inline) +- List dispatch mechanisms: CLI (`task` tool), VS Code (`runSubagent` tool), or fallback (work inline) - Update anti-patterns and constraints sections with same substitution **Fix 2: Top-and-Bottom Reinforcement (P0)** @@ -139,8 +137,7 @@ unSubagent\ tool), or fallback (work inline) **Fix 5: VS Code-Specific Hardening Block (P1)** - Move VS Code adaptations section higher (from line 458 to immediately after CRITICAL RULE) - Restructure as active enforcement block with platform detection table -- Make clear: if \ -unSubagent\ is available, it MUST be used for domain work +- Make clear: if `runSubagent` is available, it MUST be used for domain work ### Priority Ordering @@ -159,8 +156,7 @@ unSubagent\ is available, it MUST be used for domain work After implementing, test with Andreas's reproduction case: 1. Open VS Code with squadified project 2. Ask coordinator to do domain work that matches routing rule -3. Verify: coordinator dispatches via \ -unSubagent\ instead of working inline +3. Verify: coordinator dispatches via `runSubagent` instead of working inline 4. Verify: coordinator cites the routing rule when dispatching FIDO should own the test scenario. GUIDO should validate the VS Code runtime behavior. @@ -169,8 +165,7 @@ FIDO should own the test scenario. GUIDO should validate the VS Code runtime beh 1. Does CLI 1.0.11 support exclusion patterns (.copilotignore)? If yes, Fix 4 becomes simpler. 2. Should we version-gate the VS Code adaptations (detect CLI version)? -3. Is \ -unSubagent\ still the correct tool name, or has it changed? +3. Is `runSubagent` still the correct tool name, or has it changed? --- # Decision: PR Review Batch — Overlap Resolution @@ -299,10 +294,6 @@ Triaged 14 untriaged issues (3 docs, 6 community features, 3 bugs, 2 questions). **By:** Booster (CI/CD) **What:** Templates under `packages/squad-cli/templates/workflows/` and `packages/squad-sdk/templates/workflows/` are now linted by actionlint via explicit file path arguments in the new `squad-workflow-lint.yml` CI job. SC2086 findings fixed across all `>> $GITHUB_OUTPUT` / `>> $GITHUB_STEP_SUMMARY` redirects in `.squad-templates/workflows/`, `templates/workflows/`, `.github/workflows/squad-heartbeat.yml`, `squad-repo-health.yml`, and `squad-ci.yml`. Actionlint pinned to tag `v1.7.12`; shellcheck 0.10.0 installed explicitly. **Why:** Downstream repos running actionlint in their CI saw SC2086 errors in files generated by `squad upgrade` because Squad's own CI did not lint templates. The fix must live in Squad's templates — `squad upgrade` overwrites any downstream patches on every run. PR #1557. -## 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-08-19: Finding D: slash_command plus bots concurrency warning **Date:** 2026-08-19T13:30:18.326-07:00 @@ -644,18 +635,7 @@ Option B with a phased rollout — start with a single `shared/implement.md` com *(Pending — to be resolved by the team)* -### 2026-08-19: restore shared ancestry between dev and main via merge, dev-wins conflict policy ---- -author: Data -date: 2026-08-13 -status: decided -references: - - "PR #1699" - - "PR #1698 (v0.12.0 dev -> main promotion, unblocked by this)" - - "PR #1415 (tools: ['*'] fix, verified already on dev)" ---- - -# Decision: restore shared ancestry between dev and main via merge, dev-wins conflict policy +### 2026-08-13: Restore shared ancestry between dev and main via merge, dev-wins conflict policy ## Context @@ -746,7 +726,7 @@ prevents the same failure on future promotions, provided the new release-process skill gate (verify `git merge-base dev main` before starting release-prep) is followed going forward. -### 2026-07-27: 2026-07-27: Dispatch Enforcement — Stop Coordinator From Doing Domain Work Inline +### 2026-07-27: Dispatch Enforcement — Stop Coordinator From Doing Domain Work Inline **Status:** ACCEPTED (empirically validated in tamresearch1 worktree; ported to bradygaster/squad) **Proposed by:** Picard, Data, Q (review chain) **Validated by:** Ralph (E2E test report, 2026-07-27)