Skip to content

Commit a1a8e1f

Browse files
authored
Merge pull request #2066 from bradygaster/bradygaster-agent-identity-producer
Define stable Squad agent identity provenance
2 parents fa739bd + d40250a commit a1a8e1f

53 files changed

Lines changed: 9030 additions & 481 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.
Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
---
2+
"@bradygaster/squad-sdk": minor
3+
"@bradygaster/squad-cli": minor
4+
---
5+
6+
Publish and validate a versioned producer-owned agent identity provenance
7+
contract with stable IDs, rename preservation, retirement tombstones, and
8+
optional repository avatar references. Activation artifacts now carry a
9+
versioned repository-scoped work-to-agent binding linked to the exact registry
10+
revision, with explicit fail-closed omission, cross-row reconciliation, and
11+
stale-data semantics. Preset and CLI Cast registry updates now share an
12+
ABA-safe directory lock, and registry/history publication uses a durable
13+
manifest-backed roll-forward transaction plus a consistency-aware pair reader.
14+
Interrupted post-journal commits never roll back, while abandoned same-host
15+
locks recover only after the owner PID is definitively dead. Init and upgrade
16+
now create or migrate the same durable pair under that shared protocol, all
17+
production exporters and health readers reject split generations, legacy pairs
18+
migrate without an ABA window, and CLI Cast validates every casting input
19+
before its first filesystem mutation. Preset rollback now uses byte-identical
20+
compare-and-swap guards so concurrent external file and tree changes survive,
21+
and uncertain journal removal or directory fsync is reported as commit-in-doubt
22+
instead of success. These protocols provide process-crash consistency on
23+
filesystems with local atomic rename; power-loss durability additionally
24+
depends on successful file and parent directory fsync and the underlying
25+
platform and filesystem semantics.
Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"@bradygaster/squad-sdk": patch
3+
---
4+
5+
Reject revision-bearing snapshot keys when validating canonical legacy Cast genesis history.
Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
'@bradygaster/squad-cli': patch
3+
'@bradygaster/squad-sdk': patch
4+
---
5+
6+
Reject ambiguous legacy casting generations, validate complete registry/history commits before mutation, and surface structured preset rollback recovery state.
Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"@bradygaster/squad-sdk": patch
3+
---
4+
5+
Reject incomplete or malformed casting history before synchronizing team capabilities.
Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
11
{
2+
"schema": "squad-agent-provenance/v1",
3+
"schema_version": 1,
4+
"revision": 1,
5+
"generated_at": "1970-01-01T00:00:00.000Z",
26
"agents": {}
37
}

‎.squad/casting/registry.json‎

Lines changed: 22 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,26 @@
11
{
2+
"schema": "squad-agent-provenance/v1",
3+
"schema_version": 1,
4+
"revision": 1,
5+
"generated_at": "2026-09-22T00:00:00.000Z",
26
"agents": {
3-
"architect": { "created_at": "2026-09-12T12:25:45.986-07:00", "persistent_name": "architect", "universe": "descriptive", "status": "active" },
4-
"agent-orchestration-dev": { "created_at": "2026-09-12T12:25:45.986-07:00", "persistent_name": "agent-orchestration-dev", "universe": "descriptive", "status": "active" },
5-
"typescript-api-contract-designer": { "created_at": "2026-09-12T12:25:45.986-07:00", "persistent_name": "typescript-api-contract-designer", "universe": "descriptive", "status": "active" },
6-
"sdk-runtime-dev": { "created_at": "2026-09-12T12:25:45.986-07:00", "persistent_name": "sdk-runtime-dev", "universe": "descriptive", "status": "active" },
7-
"plugin-platform-dev": { "created_at": "2026-09-12T12:25:45.986-07:00", "persistent_name": "plugin-platform-dev", "universe": "descriptive", "status": "active" },
8-
"cli-dev": { "created_at": "2026-09-12T12:25:45.986-07:00", "persistent_name": "cli-dev", "universe": "descriptive", "status": "active" },
9-
"terminal-ux-dev": { "created_at": "2026-09-12T12:25:45.986-07:00", "persistent_name": "terminal-ux-dev", "universe": "descriptive", "status": "active" },
10-
"state-storage-dev": { "created_at": "2026-09-12T12:25:45.986-07:00", "persistent_name": "state-storage-dev", "universe": "descriptive", "status": "active" },
11-
"git-specialist": { "created_at": "2026-09-12T12:25:45.986-07:00", "persistent_name": "git-specialist", "universe": "descriptive", "status": "active" },
12-
"github-integration-dev": { "created_at": "2026-09-12T12:25:45.986-07:00", "persistent_name": "github-integration-dev", "universe": "descriptive", "status": "active" },
13-
"agentic-workflows-dev": { "created_at": "2026-09-12T12:25:45.986-07:00", "persistent_name": "agentic-workflows-dev", "universe": "descriptive", "status": "active" },
14-
"observability-dev": { "created_at": "2026-09-12T12:25:45.986-07:00", "persistent_name": "observability-dev", "universe": "descriptive", "status": "active" },
15-
"dotnet-agent-framework-dev": { "created_at": "2026-09-12T12:25:45.986-07:00", "persistent_name": "dotnet-agent-framework-dev", "universe": "descriptive", "status": "active" },
16-
"unit-contract-tester": { "created_at": "2026-09-12T12:25:45.986-07:00", "persistent_name": "unit-contract-tester", "universe": "descriptive", "status": "active" },
17-
"integration-e2e-tester": { "created_at": "2026-09-12T12:25:45.986-07:00", "persistent_name": "integration-e2e-tester", "universe": "descriptive", "status": "active" },
18-
"security-reviewer": { "created_at": "2026-09-12T12:25:45.986-07:00", "persistent_name": "security-reviewer", "universe": "descriptive", "status": "active" },
19-
"release-engineer": { "created_at": "2026-09-12T12:25:45.986-07:00", "persistent_name": "release-engineer", "universe": "descriptive", "status": "active" },
20-
"docs-devrel": { "created_at": "2026-09-12T12:25:45.986-07:00", "persistent_name": "docs-devrel", "universe": "descriptive", "status": "active" }
7+
"architect": { "display_name": "architect", "persistent_name": "architect", "role": "Lead Architect", "universe": "descriptive", "status": "active", "created_at": "2026-09-12T19:25:45.986Z", "updated_at": "2026-09-22T00:00:00.000Z" },
8+
"agent-orchestration-dev": { "display_name": "agent-orchestration-dev", "persistent_name": "agent-orchestration-dev", "role": "Agent Orchestration Engineer", "universe": "descriptive", "status": "active", "created_at": "2026-09-12T19:25:45.986Z", "updated_at": "2026-09-22T00:00:00.000Z" },
9+
"typescript-api-contract-designer": { "display_name": "typescript-api-contract-designer", "persistent_name": "typescript-api-contract-designer", "role": "TypeScript API Contract Designer", "universe": "descriptive", "status": "active", "created_at": "2026-09-12T19:25:45.986Z", "updated_at": "2026-09-22T00:00:00.000Z" },
10+
"sdk-runtime-dev": { "display_name": "sdk-runtime-dev", "persistent_name": "sdk-runtime-dev", "role": "SDK Runtime Engineer", "universe": "descriptive", "status": "active", "created_at": "2026-09-12T19:25:45.986Z", "updated_at": "2026-09-22T00:00:00.000Z" },
11+
"plugin-platform-dev": { "display_name": "plugin-platform-dev", "persistent_name": "plugin-platform-dev", "role": "Plugin Platform Engineer", "universe": "descriptive", "status": "active", "created_at": "2026-09-12T19:25:45.986Z", "updated_at": "2026-09-22T00:00:00.000Z" },
12+
"cli-dev": { "display_name": "cli-dev", "persistent_name": "cli-dev", "role": "CLI Engineer", "universe": "descriptive", "status": "active", "created_at": "2026-09-12T19:25:45.986Z", "updated_at": "2026-09-22T00:00:00.000Z" },
13+
"terminal-ux-dev": { "display_name": "terminal-ux-dev", "persistent_name": "terminal-ux-dev", "role": "Terminal UX Engineer", "universe": "descriptive", "status": "active", "created_at": "2026-09-12T19:25:45.986Z", "updated_at": "2026-09-22T00:00:00.000Z" },
14+
"state-storage-dev": { "display_name": "state-storage-dev", "persistent_name": "state-storage-dev", "role": "State & Storage Engineer", "universe": "descriptive", "status": "active", "created_at": "2026-09-12T19:25:45.986Z", "updated_at": "2026-09-22T00:00:00.000Z" },
15+
"git-specialist": { "display_name": "git-specialist", "persistent_name": "git-specialist", "role": "Git Specialist", "universe": "descriptive", "status": "active", "created_at": "2026-09-12T19:25:45.986Z", "updated_at": "2026-09-22T00:00:00.000Z" },
16+
"github-integration-dev": { "display_name": "github-integration-dev", "persistent_name": "github-integration-dev", "role": "GitHub Integration Engineer", "universe": "descriptive", "status": "active", "created_at": "2026-09-12T19:25:45.986Z", "updated_at": "2026-09-22T00:00:00.000Z" },
17+
"agentic-workflows-dev": { "display_name": "agentic-workflows-dev", "persistent_name": "agentic-workflows-dev", "role": "Agentic Workflows Engineer", "universe": "descriptive", "status": "active", "created_at": "2026-09-12T19:25:45.986Z", "updated_at": "2026-09-22T00:00:00.000Z" },
18+
"observability-dev": { "display_name": "observability-dev", "persistent_name": "observability-dev", "role": "Observability Engineer", "universe": "descriptive", "status": "active", "created_at": "2026-09-12T19:25:45.986Z", "updated_at": "2026-09-22T00:00:00.000Z" },
19+
"dotnet-agent-framework-dev": { "display_name": "dotnet-agent-framework-dev", "persistent_name": "dotnet-agent-framework-dev", "role": ".NET Agent Framework Engineer", "universe": "descriptive", "status": "active", "created_at": "2026-09-12T19:25:45.986Z", "updated_at": "2026-09-22T00:00:00.000Z" },
20+
"unit-contract-tester": { "display_name": "unit-contract-tester", "persistent_name": "unit-contract-tester", "role": "Unit & Contract Tester", "universe": "descriptive", "status": "active", "created_at": "2026-09-12T19:25:45.986Z", "updated_at": "2026-09-22T00:00:00.000Z" },
21+
"integration-e2e-tester": { "display_name": "integration-e2e-tester", "persistent_name": "integration-e2e-tester", "role": "Integration & E2E Tester", "universe": "descriptive", "status": "active", "created_at": "2026-09-12T19:25:45.986Z", "updated_at": "2026-09-22T00:00:00.000Z" },
22+
"security-reviewer": { "display_name": "security-reviewer", "persistent_name": "security-reviewer", "role": "Security Reviewer", "universe": "descriptive", "status": "active", "created_at": "2026-09-12T19:25:45.986Z", "updated_at": "2026-09-22T00:00:00.000Z" },
23+
"release-engineer": { "display_name": "release-engineer", "persistent_name": "release-engineer", "role": "Release Engineer", "universe": "descriptive", "status": "active", "created_at": "2026-09-12T19:25:45.986Z", "updated_at": "2026-09-22T00:00:00.000Z" },
24+
"docs-devrel": { "display_name": "docs-devrel", "persistent_name": "docs-devrel", "role": "Documentation & DevRel Engineer", "universe": "descriptive", "status": "active", "created_at": "2026-09-12T19:25:45.986Z", "updated_at": "2026-09-22T00:00:00.000Z" }
2125
}
2226
}
Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
1+
---
2+
title: Agent identity provenance
3+
description: The versioned Squad-owned contract for stable agent identity metadata.
4+
---
5+
6+
Squad publishes authoritative agent identity metadata at
7+
`.squad/casting/registry.json`. Consumers such as dashboards and renderers must
8+
use this record instead of inferring identity from a roster row, goal owner,
9+
issue assignee, pull request author or reviewer, workflow actor, branch name, or
10+
any other incidental signal.
11+
12+
## Version 1 contract
13+
14+
The root schema identifier is `squad-agent-provenance/v1`. Each key in
15+
`agents` is an immutable lowercase kebab-case agent ID. The record contains a
16+
mutable `display_name`, a compatibility alias named `persistent_name`, the
17+
agent role and universe, lifecycle timestamps, status, and an optional avatar.
18+
19+
```json
20+
{
21+
"schema": "squad-agent-provenance/v1",
22+
"schema_version": 1,
23+
"revision": 4,
24+
"transaction_id": "52ab75df-79de-44e7-b0b7-521a45b49204",
25+
"generated_at": "2026-09-21T20:00:00.000Z",
26+
"agents": {
27+
"runtime-engineer": {
28+
"display_name": "Kepler",
29+
"persistent_name": "Kepler",
30+
"role": "Runtime Engineer",
31+
"universe": "descriptive",
32+
"status": "active",
33+
"created_at": "2026-09-20T20:00:00.000Z",
34+
"updated_at": "2026-09-21T20:00:00.000Z",
35+
"avatar": {
36+
"kind": "repository-path",
37+
"path": ".squad/agents/runtime-engineer/avatar.png"
38+
}
39+
}
40+
}
41+
}
42+
```
43+
44+
`persistent_name` is retained for older Squad readers and must equal
45+
`display_name`. New consumers should use the object key as the stable ID and
46+
`display_name` for presentation.
47+
48+
`transaction_id` is additive publication metadata. Managed
49+
`casting/history.json` files carry the same `transaction_id` plus a
50+
`registry_revision` equal to the registry `revision`. Consumers that require a
51+
consistent registry/history pair must use the SDK pair reader, which validates
52+
those fields and the durable commit manifest. Registry-only consumers may
53+
continue reading `registry.json` directly.
54+
55+
## Lifecycle and collision rules
56+
57+
- **Uniqueness:** Canonical IDs use lowercase alphanumeric segments separated
58+
by single hyphens. IDs and case-folded display names are unique within one
59+
registry. Producers reject collisions rather than adding suffixes.
60+
- **Rename or recast:** The producer must supply the existing stable ID
61+
explicitly; it never discovers identity from display name, role, roster,
62+
label, path, or other incidental data. Preserve `created_at` and immutable
63+
`role`; update `display_name`, `persistent_name`, `universe`, and `updated_at`.
64+
- **Deletion:** Preserve a tombstone with `status: "retired"`, `retired_at`, and
65+
the original ID. An ID is never reassigned.
66+
- **Reactivation:** A producer may reactivate the same logical agent under its
67+
original ID. It must not assign that ID to a different role.
68+
- **Partial data:** Invalid individual records are excluded by the SDK parser
69+
and reported as a partial result. Consumers may render valid records but must
70+
expose that identity data is incomplete.
71+
- **Missing or malformed data:** Treat identity provenance as unavailable. Do
72+
not fall back to owner, assignee, author, reviewer, actor, branch, or roster
73+
display data.
74+
- **Legacy migration:** A legacy root is accepted only when every record has a
75+
canonical ID plus valid name, lifecycle, universe, and timestamps. Any
76+
malformed record rejects the whole producer update; migration never drops it.
77+
- **Concurrent producers:** Presets and CLI Cast share one durable directory
78+
lock. Registry/history updates publish through a roll-forward transaction;
79+
pair readers accept only a complete legacy pair or a stable manifest-backed
80+
pair. Each successful update observes the latest revision, increments it,
81+
and preserves all unclaimed IDs as tombstones.
82+
83+
## Consistency, durability, and recovery boundaries
84+
85+
On a local filesystem that provides atomic same-filesystem rename, the shared
86+
lock, transaction journal, commit manifest, and pair reader provide
87+
**process-crash consistency**. A crash before the journal is durable leaves the
88+
previous pair authoritative. After the journal is durable, recovery rolls the
89+
transaction forward. Pair readers retry an in-progress state for a bounded
90+
period and then reject it rather than returning a torn registry/history pair.
91+
92+
**Power-loss durability is conditional.** The implementation calls fsync on
93+
each payload or replacement file and the relevant payload and parent
94+
directories, but persistence across power loss depends on every fsync
95+
succeeding and on the operating system, storage device, and filesystem
96+
honoring those operations and atomic rename semantics. If a required file or
97+
directory fsync reports an error, the writer fails closed; it does not report
98+
the update as durably committed. A filesystem that does not provide local
99+
atomic rename guarantees, including some network filesystems, is outside the
100+
full guarantee: even if its APIs return success, power-loss durability and
101+
cross-process consistency are only as strong as that filesystem's documented
102+
semantics. Use a supported local filesystem when the full guarantee is
103+
required.
104+
105+
Stale-lock recovery deliberately favors safety over availability. Squad
106+
automatically removes an abandoned writer lock only when it is old, belongs to
107+
the current host, and the owner PID is definitively dead. An owner on another
108+
host, an indeterminate PID, or an abandoned recovery guard is not broken
109+
automatically; writers time out and require operator intervention after
110+
verifying that no writer or recovery operation is active. This can delay
111+
updates, but prevents an uncertain recovery from admitting concurrent writers.
112+
113+
## Fetch, permissions, and caching
114+
115+
Reading the registry requires repository Contents read permission and one
116+
content fetch. A repository-path avatar requires one additional content fetch
117+
for that agent. Consumers should cache the registry by Git blob SHA, ETag, or
118+
equivalent immutable revision marker and revalidate normally. The root
119+
`revision` is monotonic producer metadata, not a substitute for transport cache
120+
validation.
121+
122+
Avatar references are optional and restricted to the owning ID's exact,
123+
case-sensitive `.squad/agents/{id}/` directory. Recasts preserve an existing
124+
avatar when no avatar operation is supplied; an explicit producer clear removes
125+
it. When the field is absent, stale, inaccessible, or malformed, render no avatar. Do not
126+
generate initials, Gravatars, GitHub actor images, or other inferred identity.
127+
128+
## Work-to-agent binding contract
129+
130+
The registry does not identify which agent owns a particular goal, epic, or
131+
task. Squad activation artifacts therefore include a non-empty `Activation
132+
bindings:` JSON array using `squad-work-agent-binding/v1`:
133+
134+
```json
135+
[
136+
{
137+
"binding_schema": "squad-work-agent-binding/v1",
138+
"binding_version": 1,
139+
"producer": "squad",
140+
"repository": "owner/repository",
141+
"origin_issue": 45,
142+
"artifact": "activated",
143+
"registry_schema": "squad-agent-provenance/v1",
144+
"registry_revision": 4,
145+
"task": "1",
146+
"issue": "#2066",
147+
"epic": "1.1",
148+
"epic_issue": "#2065",
149+
"agent_id": "runtime-engineer",
150+
"epic_agent_ids": ["runtime-engineer"]
151+
}
152+
]
153+
```
154+
155+
The repository and origin issue identify the goal, `issue` identifies the task,
156+
and `epic_issue` identifies its parent work artifact. The producer copies
157+
`agent_id` values directly from the committed registry revision into the
158+
accepted plan and then the activation record. Display names, labels, owners,
159+
assignees, authors, reviewers, workflow actors, branches, and roster rows are
160+
never alternate binding sources.
161+
162+
Rename does not change historical bindings. Retirement leaves the ID resolvable
163+
through its tombstone; it does not transfer work to another agent. A current
164+
registry newer than `registry_revision` may resolve the historical ID. A
165+
binding revision newer than the available registry is stale and unavailable.
166+
Every row in one binding artifact names the same registry revision; consumers
167+
reject mixed revisions rather than reconciling rows against different identity
168+
snapshots.
169+
170+
Missing IDs are allowed only for explicitly external, non-roster, or legacy
171+
plan assignments: `agent_id` is `null` and `identity_omission_reason` explains
172+
why. If any epic member lacks an ID, its records add
173+
`epic_identity_omission_reason: "partial"` and list only known IDs. Every row
174+
for an epic carries the same sorted `epic_agent_ids` set, equal to all known
175+
task-agent IDs for that epic. The partial marker appears on every row if any
176+
task omits `agent_id`, and on no row when the epic identity set is complete.
177+
One binding document uses one registry revision and maps each epic identifier
178+
to exactly one epic issue, and each epic issue back to exactly one identifier.
179+
180+
Consumers fail closed for a missing, empty, malformed, partially valid,
181+
wrong-repository, wrong-origin, unsupported-version, unknown-ID, or
182+
future-revision binding array, and for duplicate task/issue bindings or
183+
conflicting epic mappings, revisions, identity sets, or omission markers. A partial registry may still support plain
184+
metadata rendering, but it cannot authoritatively resolve work bindings. They
185+
must not salvage valid-looking rows or infer
186+
the missing identity. Fetching the activation artifact requires Issues read;
187+
resolving its IDs adds the same one Contents fetch for the registry described
188+
above. No additional per-task fetch is required.

0 commit comments

Comments
 (0)