docs: clarify that .squad/casting/* files are identity, not two-layer state#1230
Open
tamirdresher wants to merge 1 commit into
Open
docs: clarify that .squad/casting/* files are identity, not two-layer state#1230tamirdresher wants to merge 1 commit into
tamirdresher wants to merge 1 commit into
Conversation
… state .squad/casting/* files (policy.json, registry.json, history.json) are AUTHORITATIVE IDENTITY files that should be committed to 'main' alongside team.md and routing.md. They define the agent universe, name registry, and usage history - fundamental team identity, not runtime mutable state. This change adds clarifying documentation to: - .gitignore: explicit NOTE that casting/* MUST NOT be ignored - .gitattributes: explicit NOTE that casting/* is identity, not append-only - init.ts: enhanced comments explaining casting/* classification This resolves confusion where casting files were misclassified as two-layer runtime state. Per squad.agent.md (the source of truth), casting files are 'Authoritative' and belong on main. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
🛫 PR Readiness Check
PR Scope: 📦🔧 Mixed (product + infrastructure)
|
| Status | Check | Details |
|---|---|---|
| ✅ | Single commit | 1 commit — clean history |
| ✅ | Not in draft | Ready for review |
| ❌ | Branch up to date | main is 427 commit(s) ahead — rebase recommended |
| ❌ | Copilot review | No Copilot review yet — it may still be processing |
| ❌ | Changeset present | Missing .changeset/*.md or CHANGELOG.md edit — run npx changeset add (or add skip-changelog label) |
| ✅ | Scope clean | No .squad/ or docs/proposals/ files |
| ❌ | No merge conflicts | Merge conflicts detected — resolve before review |
| ✅ | Copilot threads resolved | No Copilot review threads |
| ❌ | CI passing | No CI checks have run yet |
Files Changed (3 files, +19 −2)
| File | +/− |
|---|---|
.gitattributes |
+6 −0 |
.gitignore |
+5 −2 |
packages/squad-sdk/src/config/init.ts |
+8 −0 |
Total: +19 −2
This check runs automatically on every push. Fix any ❌ items and push again.
See CONTRIBUTING.md and PR Requirements for details.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
.squad/casting/* files (policy.json, registry.json, history.json) have been misclassified as two-layer runtime mutable state that should live on the squad-state orphan branch. This causes confusion and blocks the use of these critical team identity files.
Root Cause
The classification was unclear in the codebase. While .squad/casting/* files are correctly created and not ignored, there was no explicit documentation clarifying that they are AUTHORITATIVE IDENTITY files per squad.agent.md (the source-of-truth governance document).
Solution
Added clarifying documentation to three files:
Authority
Per .github/agents/squad.agent.md (the authoritative classification table):
These files define the agent universe, persistent name-to-ID mappings, and usage history - fundamental team identity committed to main alongside team.md and routing.md.
Files Changed