Merge remote-tracking branch 'origin/dev' into release/v1.0.0-main-promotion

Author: Copilot

.changeset/2056-doctor-remote-state-dir.md

@@ -0,0 +1,5 @@
+---
+"@bradygaster/squad-cli": patch
+---
+
+`squad doctor` now validates team state files (`team.md`, `routing.md`, `agents/`, `casting/registry.json`, `decisions.md`) against the resolved team root in remote (linked) mode instead of the local `.squad/` stub, which only holds `config.json`. Previously this caused false "file not found" failures for correctly configured `squad link` setups even though `squad status` and `squad cast` resolved the team fine. Fixes #2056.

.changeset/2106-windows-durable-casting.md

@@ -0,0 +1,5 @@
+---
+"@bradygaster/squad-sdk": patch
+---
+
+Fix `squad init` and team casting failing on Windows with `EPERM: operation not permitted, fsync`. The durable casting registry fsynced directory handles after each rename, which Windows rejects; directory flushes are now skipped on `win32`, where the file-level fsync is the only flush available. Also fixed the casting writer lock crashing with `EPERM ... rename` instead of waiting when another process already holds it on Windows, which reports a rename onto an existing directory as `EPERM` rather than POSIX `ENOTEMPTY`/`EEXIST`. Lock timeouts now name the last publish error, and releasing the lock retries briefly when Windows transiently rejects the directory rename (e.g. antivirus holding a freshly written file), instead of leaving a recovery guard that blocks later casting writers. If Windows still blocks deleting the released lock copy, release succeeds and a later release sweeps the leftover out of `.squad/casting/`.

.changeset/2107-linked-team-root-forms.md

@@ -0,0 +1,10 @@
+---
+"@bradygaster/squad-sdk": minor
+"@bradygaster/squad-cli": patch
+---
+
+Linked teams now work with either `teamRoot` form: the team repository (what `squad link` writes) or the team's `.squad/` directory (what the docs show). `resolveSquadPaths()` adds `teamSquadDir`, the team's squad directory for both forms, and `resolveSquadState()` roots local-backend storage there. `squad loop`/`watch`, `squad cast`, and the state MCP server read team state from `teamSquadDir`, so `squad loop` no longer reports "No squad found" for the docs form, and `squad_decide` no longer writes decisions outside `.squad/` for the `squad link` form. Closes #2107.
+
+`teamSquadDir` is a required field on the exported `ResolvedSquadPaths` type, so code that constructs that type must now set it. `@bradygaster/squad-sdk/tools` also exports `MUTABLE_STATE_PATHS` and `isMutableStateKey()`, the list of state paths that the state tools can write.
+
+If you linked a team with `squad link`: state that the state MCP server wrote to the team repo root (`decisions.md`, `decisions/inbox/`, `casting/policy.json`, `agents/*/history.md`, `log/`, `orchestration-log/`, `sessions/`, `.scratch/`, `identity/`) now belongs in `<team>/.squad/`. Squad does not move it. Run `squad doctor` to find leftovers. It lists the `.md` and `.json` files to move to the same relative path under `<team>/.squad/` (for example `<team>/identity/now.md` to `<team>/.squad/identity/now.md`), and the files that already exist there, which you must merge by hand without overwriting the newer state. Do not replace the existing `<team>/.squad/` directories. Skills that `squad_skill` wrote went to `.github/skills/` in the folder that contains the team repo; move any you want to keep to `<team>/.github/skills/`. Doctor does not check that folder.

.changeset/formalize-charter-profile.md

@@ -0,0 +1,5 @@
+---
+'@bradygaster/squad-sdk': minor
+---
+
+Add the draft `squad-charter/v0.1` artifact profile, explicit conformance profile selection, validation-before-runtime compilation, typed diagnostics and operation-exact capability metadata, canonical and lossless extension-preserving serialization, a schema-defined language-neutral conformance manifest with complete diagnostic coverage, and implementation-independent specification documents.

.gitattributes

@@ -56,4 +56,7 @@ Dockerfile.* text eol=lf
 # Squad: union merge for append-only team state files
 .squad/fact-checker/audit-trail.md merge=union
 
-.github/workflows/*.lock.yml linguist-generated=true
+.github/workflows/*.lock.yml linguist-generated=true
+
+# Charter conformance binds exact document bytes across platform checkouts.
+docs/specification/charter-v0.1.md text eol=lf

.github/workflows/squad-ci.yml

@@ -745,9 +745,7 @@ jobs:
           cache: npm
 
       - name: Install verifier dependencies
-        run: |
-          npm config set registry "https://packagefeedproxy.microsoft.io/npm/"
-          npm ci --ignore-scripts
+        run: npm ci --ignore-scripts --registry=https://registry.npmjs.org/
 
       - name: Install gh-aw v0.89.22 (pinned)
         run: |

.squad-templates/skills/gh-aw-enlistment/SKILL.md

@@ -382,13 +382,27 @@ gh pr create \
   --base "${default_branch}" \
   --title "ci: add Squad agentic workflow" \
   --body "Installs and strictly compiles the supported Squad GH-AW workflows."
-gh pr edit --add-reviewer @copilot
+
+# Copilot's review identity is a GraphQL Bot, not a User/Team — the REST
+# `gh pr edit --add-reviewer @copilot` path silently no-ops for it. Request the
+# review through the verified GraphQL path instead:
+pr_node_id="$(gh pr view --json id --jq '.id')"
+gh api graphql -f query='
+  mutation($pr: ID!) {
+    requestReviewsByLogin(input: { pullRequestId: $pr, botLogins: ["copilot-pull-request-reviewer"] }) {
+      pullRequest { number }
+    }
+  }' -f pr="${pr_node_id}" || echo "Could not request a Copilot review via GraphQL; open the PR in the GitHub UI and add Copilot as a reviewer manually (Reviewers -> Copilot)." >&2
 gh pr checks --watch
 ```
 
 - Open the PR against the **runtime-captured** `${default_branch}`, not a hardcoded
   `main`.
-- Request Copilot review, address feedback, and wait for required checks.
+- Request Copilot review via the GraphQL `requestReviewsByLogin` mutation
+  (never the REST `--add-reviewer` shortcut, which silently no-ops for the
+  Copilot Bot reviewer), address feedback, and wait for required checks. If
+  the GraphQL call fails, add Copilot as a reviewer manually from the PR's
+  GitHub UI.
 
 ### 9. Verify the native review contract after merge
 
@@ -497,7 +511,13 @@ git push -u origin HEAD
 gh pr create --base "${default_branch}" \
   --title "ci: add Squad agentic workflow" \
   --body "Installs and strictly compiles the supported Squad GH-AW workflows."
-gh pr edit --add-reviewer @copilot   # then wait for review + checks; DO NOT merge
+pr_node_id="$(gh pr view --json id --jq '.id')"
+gh api graphql -f query='
+  mutation($pr: ID!) {
+    requestReviewsByLogin(input: { pullRequestId: $pr, botLogins: ["copilot-pull-request-reviewer"] }) {
+      pullRequest { number }
+    }
+  }' -f pr="${pr_node_id}"   # Bot-aware review request; then wait for review + checks; DO NOT merge
 ```
 
 ### ✓ Correct: STOP on an undocumented safe-update entry

docs/package-lock.json

@@ -0,0 +1,169 @@
+# Squad Specification
+
+**Core version:** 0.1
+
+**Status:** Working Draft
+
+**Draft date:** 2026-09-25
+
+**Working-draft provenance:** [PR #2074](https://github.com/bradygaster/squad/pull/2074)
+contains the combined Core, Charter, and suite revision. The suite draft
+originated in [PR #2078](https://github.com/bradygaster/squad/pull/2078);
+the combined branch preserves its source-commit provenance.
+
+The source index keeps `publication.revision` and `publication.digest` null
+while it is a working draft. After review, the exact head SHA is recorded in
+the PR body and review report. A publication pipeline may copy the source index
+into a release artifact, set `publication.status` to `published`, insert that
+already-existing reviewed head SHA, and compute the release artifact digest.
+The derived release index is attached to the tag or release; it is not committed
+back onto the same commit. This records an immutable revision in the suite
+index without a self-referential hash that would invalidate the commit.
+
+Publication metadata is not a conformance-claim binding. Every claimable
+profile instead carries a non-null `revision` object in the suite registry and
+its executable manifest. For Charter v0.1, that object binds the exact Charter
+document bytes and the canonical manifest evidence payload with SHA-256
+digests. This makes working-draft claims reproducible while publication
+metadata remains null.
+
+**Document class:** Informative registry and navigation index
+
+**Foundation profile:** [Squad Charter Profile v0.1](charter-v0.1.md)
+
+This directory maps a working inventory of stable or observable Squad surfaces,
+including composition and initialization capabilities without profiles in
+the [artifact inventory](artifact-inventory.md). It does not yet specify the
+complete model for how independent Squads compose and interact. Publication
+status is independent from maturity: this suite is an unpublished working
+draft. Charter is the only profile with executable conformance evidence.
+
+## Maturity taxonomy
+
+The suite uses exactly five maturity values:
+
+| Maturity | Meaning | Claimable |
+|---|---|---|
+| `executable-normative-draft` | Normative working draft with an executable manifest and schema | Yes, only identifiers declared by that manifest; not published |
+| `experimental-normative-draft` | Normative working draft whose rules are exercised only through dependent profiles or partial evidence | No standalone claims |
+| `experimental-schema` | Machine-valid schema or fixture, but no complete conformance manifest | No |
+| `requirements-draft` | Conceptual and behavioral requirements awaiting portable fixtures | No |
+| `informative-draft` | Coverage, observations, or volatile requirements | No |
+
+The document-class vocabulary is `normative-profile`, `normative-schema`,
+`requirements`, and `informative`. The only conformance-class vocabulary is
+`canonical`, `compatible`, `legacy`, and `runtime`. Implementation roles
+(`producer`, `consumer`, `editor`, `validator`, and `executor`) describe what
+software does; they are not claims.
+
+Capability identifiers use one grammar:
+`squad-<profile>/v<major>.<minor>/<operation>`. The suite defines no `#operation`
+alias. A registry entry without an executable manifest has no claimable
+capabilities or conformance classes.
+
+## Document registry
+
+`Schema/manifest` uses `schema`, `manifest`, `fixture`, or `none`. Known
+deviations are summarized here and expanded in the
+[coverage matrix](artifact-inventory.md#known-unstable-and-non-conforming-behavior).
+
+| ID | Maturity / class | Dependencies | Claimable capabilities | Schema/manifest | Implementation status | Known deviations | Reader entry path |
+|---|---|---|---|---|---|---|---|
+| `squad-core/v0.1` | `experimental-normative-draft` / normative profile | None | None | None | Normative rules are exercised by Charter; no standalone Core manifest | Canonical JSON and standalone Core cases incomplete | [Core](core-v0.1.md), then Charter |
+| `squad-interop/v0.1` | `requirements-draft` / requirements | Core | None | Reference evidence schema; no manifest | Schema and example records inform future profile design | No discovery, relational-invariant, or replay corpus | [Interoperability](interoperability-conventions-v0.1.md) |
+| `squad-charter/v0.1` | `executable-normative-draft` / normative profile | Core | `squad-charter/v0.1/parse`, `squad-charter/v0.1/validate`, `squad-charter/v0.1/edit`, `squad-charter/v0.1/legacy-consume`, `squad-charter/v0.1/runtime` | Manifest, schema, and immutable revision binding | Parser, validator, editor, compiler, and cases implemented | None registered | [Charter](charter-v0.1.md) |
+| `squad-team-routing/v0.1` | `requirements-draft` / requirements | Core, Interop, Charter | None | None | Roster and routing exist in multiple shapes | Fallback and ambiguity differ | [Roster, then routing](team-routing-v0.1.md) |
+| `squad-configuration-casting/v0.1` | `requirements-draft` / requirements | Core, Interop, Team/Routing | None | None | Configuration, registry, and history implemented | Legacy shapes and runtime-only keys | [Configuration, casting, provenance](configuration-casting-v0.1.md) |
+| `squad-governance-review/v0.1` | `requirements-draft` / requirements | Core, Interop, Team/Routing | None | Reference schema and rejection fixture; no manifest | TypeScript checks exercise implementation expectations only | No portable relational-invariant or transition corpus | [Evidence shape, then promotion criteria](governance-review-v0.1.md) |
+| `squad-execution-preferences/v0.1` | `requirements-draft` / requirements | Core, Interop, Charter, Configuration/Casting | None | None | Runtime selection exists | Provider catalogs and fallback are policy | [Execution preferences](execution-preferences-v0.1.md) |
+| `squad-planning-activation/v0.1` | `requirements-draft` / requirements | Core, Interop, Team/Routing, Work Lifecycle | None | None | gh-aw planning records exist | Safe-output and limits are provider-specific | [Planning and activation](planning-activation-v0.1.md) |
+| `squad-ceremony/v0.1` | `requirements-draft` / requirements | Core, Interop, Team/Routing | None | None | Builder preserves triggers and schedules | Event names, `auto`, and cooldown are unstable | [Ceremonies](ceremony-v0.1.md) |
+| `squad-work-lifecycle/v0.1` | `requirements-draft` / requirements | Core, Interop, Team/Routing, Governance | None | None | Neutral state design only | No shared transition traces | [Neutral lifecycle](work-lifecycle-v0.1.md) |
+| `squad-work-github/v0.1` | `requirements-draft` / requirements binding | Interop, Work Lifecycle, Governance | None | None | GitHub adapters exist | No deterministic provider transcripts | [GitHub binding](github-work-lifecycle-binding-v0.1.md) |
+| `squad-coordination-handoff/v0.1` | `requirements-draft` / requirements | Core, Interop, Team/Routing | None | None | Session and handoff implementations exist | Ordering and recovery are provider-specific | [Coordination](coordination-handoff-v0.1.md) |
+| `squad-automation/v0.1` | `requirements-draft` / requirements | Core, Interop, Coordination | None | None | Local and GitHub schedulers exist | Time, retry, and drift evidence differ | [Automation](automation-v0.1.md) |
+| `squad-state-memory-requirements/v0.1` | `informative-draft` / informative | Core, Interop | None | None | Several state and memory providers exist | No common authority, recovery, or privacy corpus | [State authority, then memory classification](state-memory-requirements-v0.1.md) |
+| `squad-portable-bundle/v1.0` | `informative-draft` / observed implementation surface | Core and Interop rules apply conceptually | None | Tested JSON shape; no published schema or manifest | `squad export` and `squad import` round-trip team, routing, decisions, casting, agents, and skills | Bundle `1.0` does not use Core profile grammar; histories, decisions, skills, and casting policy can contain sensitive data | [Coverage and promotion requirements](artifact-inventory.md#portable-export-and-import-bundle) |
+
+The machine-readable registry is
+[`test-fixtures/spec/suite-v0.1/index.json`](../../test-fixtures/spec/suite-v0.1/index.json).
+The governance JSON is a reference fixture, not portable conformance evidence.
+Charter v0.1 is the only registered profile with a manifest, conformance
+classes, capability identifiers, and immutable claim revisions.
+
+## Textual dependency adjacency and DAG
+
+Adjacency list:
+
+```text
+squad-core/v0.1 -> []
+squad-interop/v0.1 -> [squad-core/v0.1]
+squad-charter/v0.1 -> [squad-core/v0.1]
+squad-team-routing/v0.1 -> [squad-core/v0.1, squad-interop/v0.1, squad-charter/v0.1]
+squad-configuration-casting/v0.1 -> [squad-core/v0.1, squad-interop/v0.1, squad-team-routing/v0.1]
+squad-governance-review/v0.1 -> [squad-core/v0.1, squad-interop/v0.1, squad-team-routing/v0.1]
+squad-execution-preferences/v0.1 -> [squad-core/v0.1, squad-interop/v0.1, squad-charter/v0.1, squad-configuration-casting/v0.1]
+squad-work-lifecycle/v0.1 -> [squad-core/v0.1, squad-interop/v0.1, squad-team-routing/v0.1, squad-governance-review/v0.1]
+squad-work-github/v0.1 -> [squad-interop/v0.1, squad-work-lifecycle/v0.1, squad-governance-review/v0.1]
+squad-planning-activation/v0.1 -> [squad-core/v0.1, squad-interop/v0.1, squad-team-routing/v0.1, squad-work-lifecycle/v0.1]
+squad-ceremony/v0.1 -> [squad-core/v0.1, squad-interop/v0.1, squad-team-routing/v0.1]
+squad-coordination-handoff/v0.1 -> [squad-core/v0.1, squad-interop/v0.1, squad-team-routing/v0.1]
+squad-automation/v0.1 -> [squad-core/v0.1, squad-interop/v0.1, squad-coordination-handoff/v0.1]
+squad-state-memory-requirements/v0.1 -> [squad-core/v0.1, squad-interop/v0.1]
+squad-portable-bundle/v1.0 -> [conceptual Core and Interop constraints; no profile claim]
+```
+
+DAG reading order:
+
+```text
+Core
+├── Charter (only claimable profile)
+├── Interop requirements and reference schema
+│   ├── Team/Routing
+│   │   ├── Configuration/Casting
+│   │   │   └── Execution Preferences
+│   │   ├── Governance
+│   │   │   └── Work Lifecycle
+│   │   │       ├── GitHub Binding
+│   │   │       └── Planning/Activation
+│   │   ├── Ceremony
+│   │   └── Coordination
+│   │       └── Automation
+│   └── State/Memory Requirements
+└── Portable Bundle observation (applies Core/Interop constraints without a claim)
+```
+
+There is no dependency cycle. Provider-neutral requirements precede the GitHub
+binding. State authority and memory classification remain separate promotion
+tracks. This composition diagram is informative: dependency edges do not confer
+transitive capabilities or conformance claims.
+
+## External reference policy
+
+Material external assumptions use stable, versioned, section-level links and
+are labeled normative or informative in the document that imports them. Core
+[§2](core-v0.1.md#2-normative-references) imports BCP 14, RFC 3339, and
+CommonMark 0.31.2. Interoperability
+[§10](interoperability-conventions-v0.1.md#10-versioned-references-and-precedents)
+and the GitHub binding
+[§8](github-work-lifecycle-binding-v0.1.md#8-versioned-provider-assumptions-and-references)
+identify their narrower assumptions. An informative precedent does not become
+a suite requirement merely by being cited.
+
+`test/specification-suite.test.ts` deterministically checks every Markdown file
+in this directory for relative targets, local heading anchors, and absolute
+HTTPS external citations. It also verifies every indexed specification,
+schema, manifest, and fixture path. The check is intentionally offline:
+external URL availability and remote anchor existence remain review-time or
+publication-pipeline checks.
+
+## Versioning policy
+
+Profile identifiers use `vMAJOR.MINOR`; mutable state revisions, provider API
+versions, implementation versions, and the observed portable-bundle `1.0`
+version are distinct. Draft documents may change before promotion. Only a
+`publication.status` of `published` denotes an immutable publication; published
+normative revisions are immutable except for dated errata, and behavior changes
+require a new profile version. Claimable working drafts remain bound to exact
+content digests through each profile's `revision` object; mutable branch names,
+pull request numbers, and null publication fields are never claim revisions.