docs: clarify that .squad/casting/* files are identity, not two-layer state by tamirdresher · Pull Request #1230 · github/squad

tamirdresher · 2026-06-08T12:16:48Z

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:

.gitignore - Added explicit NOTE that casting/* MUST be committed to main, not ignored
.gitattributes - Added NOTE explaining that casting/* files are identity (not append-only mutable state) and don't need union merge
packages/squad-sdk/src/config/init.ts - Enhanced comments explaining the correct classification

Authority

Per .github/agents/squad.agent.md (the authoritative classification table):

.squad/casting/policy.json: Authoritative casting config
.squad/casting/registry.json: Authoritative name registry
.squad/casting/history.json: Derived / append-only

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

.gitignore
.gitattributes
packages/squad-sdk/src/config/init.ts

github-actions · 2026-06-08T12:17:01Z

🛫 PR Readiness Check

ℹ️ This comment updates on each push. Last checked: commit cdbb998

PR Scope: 📦🔧 Mixed (product + infrastructure)

⚠️ 3 item(s) to address before review

Status	Check	Details
❌	Single commit	2 commits — consider squashing before review
✅	Not in draft	Ready for review
✅	Branch up to date	Up to date with dev
❌	Copilot review	No Copilot review yet — it may still be processing
✅	Changeset present	Changeset file found
✅	Scope clean	No .squad/ or docs/proposals/ files
✅	No merge conflicts	No merge conflicts
✅	Copilot threads resolved	0 active Copilot thread(s) resolved (5 outdated skipped)
❌	CI passing	7 check(s) still running

Files Changed (4 files, +24 −3)

File	+/−
`.changeset/casting-identity-not-state.md`	+5 −0
`.gitattributes`	+6 −0
`.gitignore`	+5 −3
`packages/squad-sdk/src/config/init.ts`	+8 −0

Total: +24 −3

This check runs automatically on every push. Fix any ❌ items and push again.
See CONTRIBUTING.md and PR Requirements for details.

bradygaster

I can't approve this as written: the new comments treat all of .squad/casting/* as authoritative identity committed to main, but .github/agents/squad.agent.md classifies .squad/casting/history.json as Derived / append-only mutable state while only policy.json and registry.json are authoritative. Please narrow the wording or call out history.json as the exception.

bradygaster

✅ Flight approves. Minor nit on history.json classification noted in comments but non-blocking for this docs clarification PR. The directional message (casting = identity, not state) is correct and valuable.

… 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>

github-actions · 2026-06-14T04:13:09Z

🟡 Impact Analysis — PR #1230

Risk tier: 🟡 MEDIUM

📊 Summary

Metric	Count
Files changed	4
Files added	1
Files modified	3
Files deleted	0
Modules touched	2

🎯 Risk Factors

4 files changed (≤5 → LOW)
2 modules touched (2-4 → MEDIUM)

📦 Modules Affected

root (3 files)

.changeset/casting-identity-not-state.md
.gitattributes
.gitignore

squad-sdk (1 file)

packages/squad-sdk/src/config/init.ts

This report is generated automatically for every PR. See #733 for details.

Copilot

Pull request overview

This PR updates documentation/comments to clarify how .squad/casting/* files should be treated (identity/config vs runtime mutable state), aiming to reduce confusion about whether these files belong in normal commits or in the squad-state backend.

Changes:

Add notes in .gitignore to discourage ignoring .squad/casting/*.
Add notes in .gitattributes explaining why casting files are not included in union-merge rules.
Expand comments in packages/squad-sdk/src/config/init.ts explaining casting file classification relative to ignore/merge-driver behavior.

Reviewed changes

Copilot reviewed 2 out of 3 changed files in this pull request and generated 5 comments.

File	Description
`packages/squad-sdk/src/config/init.ts`	Adds clarifying comments near `.gitattributes`/`.gitignore` scaffolding about casting vs runtime state.
`.gitignore`	Adds a repo-level note about not ignoring `.squad/casting/*`.
`.gitattributes`	Adds a note about casting files and union merge behavior.

+  // Append-only mutable state files use union merge to handle concurrent appends.
+  // Note: .squad/casting/* files are identity (not mutable) so they don't need
+  // union merge and are NOT listed here.


+  // Note: .squad/casting/* is AUTHORITATIVE IDENTITY (team-defined agent
+  // universe, persistent name registry, history). It belongs on 'main', not
+  // on the squad-state orphan branch. Do NOT add casting/* to ignoreEntries.


  if (missingIgnore.length > 0) {
    const block = (existingIgnore && !existingIgnore.endsWith('\n') ? '\n' : '')
      + '# Squad: ignore runtime state (logs, inbox, sessions)\n'
+      + '# Note: .squad/casting/* is identity and MUST be committed to main, not ignored\n'


+# NOTE: .squad/casting/* files are AUTHORITATIVE IDENTITY (team-defined agent
+# universe/roles, persistent name registry, universe assignment history).
+# They are committed to 'main' like team.md and routing.md, not to squad-state.
+# They do NOT need union merge and are intentionally NOT listed above.


 .squad/log/** merge=union
 .squad/orchestration-log/** merge=union


…arifications Policy Gates noticed the init.ts touch (pure comment additions clarifying that .squad/casting/* is identity, not mutable state) and asked for a changeset. Adding one — patch bump. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

bradygaster reviewed Jun 13, 2026

View reviewed changes

bradygaster previously approved these changes Jun 13, 2026

View reviewed changes

tamirdresher dismissed bradygaster’s stale review via ef50336 June 14, 2026 04:06

tamirdresher force-pushed the fix/casting-classification-hook branch 2 times, most recently from ef50336 to 9e404fa Compare June 14, 2026 04:11

tamirdresher changed the base branch from main to dev June 14, 2026 04:11

Copilot AI review requested due to automatic review settings June 14, 2026 04:13

tamirdresher force-pushed the fix/casting-classification-hook branch from 9e404fa to ef50336 Compare June 14, 2026 04:13

Copilot started reviewing on behalf of tamirdresher June 14, 2026 04:13

View session

Copilot AI reviewed Jun 14, 2026

View reviewed changes

tamirdresher merged commit ae6f4e7 into github:dev Jun 14, 2026
14 checks passed

tamirdresher mentioned this pull request Jun 14, 2026

chore: promote v0.10.1 dev → main + v0.10 stabilisation blog post #1313

Merged

4 tasks

Navigation Menu

Repository navigation

docs: clarify that .squad/casting/* files are identity, not two-layer state - #1230

docs: clarify that .squad/casting/* files are identity, not two-layer state#1230
tamirdresher merged 2 commits into
github:devfrom
tamirdresher:fix/casting-classification-hook

tamirdresher commented Jun 8, 2026

Uh oh!

github-actions Bot commented Jun 8, 2026 •

edited

Loading

Uh oh!

bradygaster left a comment

Uh oh!

bradygaster left a comment

Uh oh!

github-actions Bot commented Jun 14, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		.squad/log/** merge=union
		.squad/orchestration-log/** merge=union

Conversation

tamirdresher commented Jun 8, 2026

Problem

Root Cause

Solution

Authority

Files Changed

Uh oh!

github-actions Bot commented Jun 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🛫 PR Readiness Check

⚠️ 3 item(s) to address before review

Files Changed (4 files, +24 −3)

Uh oh!

bradygaster left a comment

Choose a reason for hiding this comment

Uh oh!

bradygaster left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Jun 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🟡 Impact Analysis — PR #1230

📊 Summary

🎯 Risk Factors

📦 Modules Affected

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

github-actions Bot commented Jun 8, 2026 •

edited

Loading

github-actions Bot commented Jun 14, 2026 •

edited

Loading