edify-agents-cli 0.2.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (102) hide show
  1. edify/__init__.py +19 -0
  2. edify/__main__.py +6 -0
  3. edify/_toml.py +286 -0
  4. edify/agents.py +261 -0
  5. edify/anim.py +499 -0
  6. edify/assets/commands/build.md +64 -0
  7. edify/assets/commands/plan.md +68 -0
  8. edify/assets/commands/spec.md +63 -0
  9. edify/assets/commands/tasks.md +65 -0
  10. edify/assets/commands/verify.md +67 -0
  11. edify/assets/formats/plan.example.md +455 -0
  12. edify/assets/formats/plan.format.md +128 -0
  13. edify/assets/formats/spec.example.md +483 -0
  14. edify/assets/formats/spec.format.md +116 -0
  15. edify/assets/formats/tasks.example.md +712 -0
  16. edify/assets/formats/tasks.format.md +199 -0
  17. edify/assets/harvest/harvest.md +91 -0
  18. edify/assets/harvest/sources.md +295 -0
  19. edify/assets/harvest/vocab.md +52 -0
  20. edify/assets/manifest.md +30 -0
  21. edify/assets/mcp/default-registry.md +66 -0
  22. edify/assets/skills/adversary.md +61 -0
  23. edify/assets/skills/debugger.md +64 -0
  24. edify/assets/skills/implementer-general.md +53 -0
  25. edify/assets/skills/implementer-go.md +63 -0
  26. edify/assets/skills/implementer-node.md +61 -0
  27. edify/assets/skills/implementer-postgres.md +63 -0
  28. edify/assets/skills/implementer-python.md +65 -0
  29. edify/assets/skills/implementer-react.md +65 -0
  30. edify/assets/skills/planner.md +58 -0
  31. edify/assets/skills/test-writer-node.md +64 -0
  32. edify/assets/skills/test-writer-python.md +60 -0
  33. edify/assets/skills/verifier.md +67 -0
  34. edify/assets/templates/CLAUDE.md +18 -0
  35. edify/assets.py +77 -0
  36. edify/cli.py +681 -0
  37. edify/commands/__init__.py +1 -0
  38. edify/commands/check_cmd.py +72 -0
  39. edify/commands/doctor_cmd.py +206 -0
  40. edify/commands/feedback_cmd.py +90 -0
  41. edify/commands/governance_cmd.py +65 -0
  42. edify/commands/graph_cmd.py +156 -0
  43. edify/commands/harvest_cmd.py +538 -0
  44. edify/commands/init_cmd.py +333 -0
  45. edify/commands/init_new_cmd.py +151 -0
  46. edify/commands/license_cmd.py +80 -0
  47. edify/commands/mcp_cmd.py +159 -0
  48. edify/commands/self_cmd.py +185 -0
  49. edify/commands/setup_cmd.py +79 -0
  50. edify/commands/skills_cmd.py +177 -0
  51. edify/commands/upgrade_cmd.py +178 -0
  52. edify/context.py +57 -0
  53. edify/conventions.py +275 -0
  54. edify/detect.py +313 -0
  55. edify/distribution.py +40 -0
  56. edify/errors.py +66 -0
  57. edify/feedback.py +207 -0
  58. edify/formats/__init__.py +11 -0
  59. edify/formats/check.py +573 -0
  60. edify/formats/document.py +238 -0
  61. edify/formats/finding.py +50 -0
  62. edify/formats/fix.py +114 -0
  63. edify/formats/mcp.py +126 -0
  64. edify/formats/plan.py +151 -0
  65. edify/formats/skill.py +139 -0
  66. edify/formats/spec.py +164 -0
  67. edify/formats/tasks.py +321 -0
  68. edify/governance.py +316 -0
  69. edify/graph/__init__.py +11 -0
  70. edify/graph/extract.py +351 -0
  71. edify/graph/ignore.py +107 -0
  72. edify/graph/langs/__init__.py +93 -0
  73. edify/graph/langs/ctags.py +145 -0
  74. edify/graph/langs/markdown.py +41 -0
  75. edify/graph/langs/patterns.py +361 -0
  76. edify/graph/langs/python_ast.py +154 -0
  77. edify/graph/langs/sqlish.py +86 -0
  78. edify/graph/model.py +102 -0
  79. edify/graph/queries.py +211 -0
  80. edify/graph/store.py +157 -0
  81. edify/harvest/__init__.py +28 -0
  82. edify/harvest/ledger.py +191 -0
  83. edify/harvest/screen.py +236 -0
  84. edify/harvest/sources.py +298 -0
  85. edify/host.py +345 -0
  86. edify/interview.py +354 -0
  87. edify/library.py +176 -0
  88. edify/licensing/__init__.py +30 -0
  89. edify/licensing/ed25519.py +154 -0
  90. edify/licensing/projects.py +223 -0
  91. edify/licensing/tier.py +172 -0
  92. edify/licensing/token.py +149 -0
  93. edify/paths.py +282 -0
  94. edify/selfinstall.py +244 -0
  95. edify/skills.py +108 -0
  96. edify/tsv.py +109 -0
  97. edify/ui.py +334 -0
  98. edify_agents_cli-0.2.0.dist-info/METADATA +408 -0
  99. edify_agents_cli-0.2.0.dist-info/RECORD +102 -0
  100. edify_agents_cli-0.2.0.dist-info/WHEEL +4 -0
  101. edify_agents_cli-0.2.0.dist-info/entry_points.txt +2 -0
  102. edify_agents_cli-0.2.0.dist-info/licenses/LICENSE +21 -0
@@ -0,0 +1,712 @@
1
+ ---
2
+ feature: team-invitations
3
+ spec: spec.md
4
+ plan: —
5
+ status: approved
6
+ phases: 8
7
+ tasks: 16
8
+ date: 2026-08-06
9
+ ---
10
+
11
+ # tasks — team invitations
12
+
13
+ > **This file is the worked example for `04-tasks-format.md`.** It is a complete plan
14
+ > for a real-shaped feature in a TypeScript / Postgres / React codebase: an admin
15
+ > invites someone by email, the invitee opens a link and joins the workspace. Read it
16
+ > for calibration — how much precision is enough, what a good pattern pointer looks
17
+ > like, how steps are written so a cheap model never has to choose. Do not fill it in
18
+ > as a template; a plan is derived from a spec and a graph, never from a shape.
19
+ >
20
+ > This feature has **no `plan.md`**, and that is the normal case: it introduces no new
21
+ > technology, spans one milestone, and needs no cross-cutting strategy
22
+ > (`03-plan-format.md` §1). `../plan-ex.md` is the example for work that does.
23
+
24
+ ## Phases
25
+
26
+ | # | phase | tasks | parallel-safe | exit check |
27
+ |---|---|---|---|---|
28
+ | 0 | Foundation | T-1 | — | `npm run build` |
29
+ | 1 | Contracts — **frozen at phase end** | T-2, T-3 | — | `npm run migrate:test && npm run typecheck` |
30
+ | 2 | **Verification** — assertions as failing tests | T-4, T-5 | T-4 ∥ T-5 | `npm test -- invitations` reports **17 failing, 0 passing** |
31
+ | 3 | Core | T-6, T-7 | T-6 ∥ T-7 | `npm test -- invitations/service` |
32
+ | 4 | Surfaces | T-8, T-9, T-10, T-11 | T-8 ∥ T-9 ∥ T-10 ∥ T-11 | `npm test -- invitations && npm run typecheck` |
33
+ | 5 | Integration | T-12, T-13 | — | `npm run test:e2e -- invitations` |
34
+ | 6 | Hardening | T-14, T-15 | T-14 ∥ T-15 | `npm test -- invitations` |
35
+ | 7 | Proof | T-16 | — | see T-16 |
36
+
37
+ Phase 4's four tasks are parallel-safe because their file sets and the dependents of
38
+ those files are disjoint — computed with `edify graph overlap`, not asserted. Phase 1
39
+ and phase 5 are serial by nature: one migration and one wiring pass each need the whole
40
+ picture.
41
+
42
+ **Read phase 2's exit check carefully: it asserts failure.** After phase 2 this feature
43
+ has seventeen red tests and no implementation, which is the correct state of a codebase
44
+ that has decided what finished means and is not finished. Every phase after it is
45
+ measured by how much of that red turns green — a count anyone can watch, rather than a
46
+ series of claims about progress.
47
+
48
+ ---
49
+
50
+ ## Phase 0 · Foundation
51
+
52
+ ### T-1 · Add the invitation config block and feature flag
53
+
54
+ Phase 0 · Role build · Skill implementer-node · Size xs
55
+ Discharges CL-1
56
+ Depends on — · Parallel with —
57
+
58
+ Files
59
+
60
+ | path | range | action |
61
+ |---|---|---|
62
+ | src/config/index.ts | 44-71 | edit |
63
+ | src/config/index.test.ts | 30-58 | edit |
64
+ | .env.example | 12-18 | edit |
65
+
66
+ Follow the pattern at
67
+ - `src/config/index.ts:22-43` — the `sessions` block: same `z.object` shape, same
68
+ `parseEnv` call, same default-plus-override style. Copy it exactly.
69
+ - `src/config/index.test.ts:12-29` — the test for that block, including how missing
70
+ env vars are asserted.
71
+
72
+ Steps
73
+ 1. In `src/config/index.ts`, after the `sessions` block ending at line 43, add an
74
+ `invitations` block with three keys: `ttlHours` (number, default `72`),
75
+ `maxPerHour` (number, default `20`), `enabled` (boolean, default `false`).
76
+ 2. Register the three env vars in the same `parseEnv` call the `sessions` block uses:
77
+ `INVITE_TTL_HOURS`, `INVITE_MAX_PER_HOUR`, `INVITE_ENABLED`.
78
+ 3. Add the three names to `.env.example` under the existing `# features` comment at
79
+ line 12, each with its default as the value.
80
+ 4. In `src/config/index.test.ts`, add a case mirroring the one at lines 12-29 that
81
+ asserts the defaults apply when the env vars are absent.
82
+
83
+ Done when
84
+ - `npm test -- config` passes
85
+ - `npm run build` succeeds
86
+ - `grep INVITE_ .env.example` returns three lines
87
+
88
+ ---
89
+
90
+ ## Phase 1 · Contracts — frozen at phase end
91
+
92
+ Everything this phase produces is fixed when it ends. A later task that needs one of
93
+ these shapes changed stops and becomes a `/tasks` amendment.
94
+
95
+ ### T-2 · Create the invitations table and its migration
96
+
97
+ Phase 1 · Role data · Skill implementer-postgres · Size s
98
+ Discharges REQ-1, REQ-3, CL-4
99
+ Depends on — · Parallel with —
100
+
101
+ Files
102
+
103
+ | path | range | action |
104
+ |---|---|---|
105
+ | migrations/0031_invitations.up.sql | — | new |
106
+ | migrations/0031_invitations.down.sql | — | new |
107
+ | src/db/schema.ts | 118-146 | edit |
108
+
109
+ Follow the pattern at
110
+ - `migrations/0027_members.up.sql:1-24` — the same table conventions: `id uuid primary
111
+ key default gen_random_uuid()`, `created_at timestamptz not null default now()`,
112
+ `workspace_id` with `on delete cascade`, and the trailing index block.
113
+ - `migrations/0027_members.down.sql:1-3` — the down migration is always a bare
114
+ `drop table if exists ... cascade;`.
115
+ - `src/db/schema.ts:92-117` — the `members` table type, exported and added to the
116
+ `Tables` union at line 146.
117
+
118
+ Steps
119
+ 1. Write `migrations/0031_invitations.up.sql` creating table `invitations` with
120
+ columns: `id`, `workspace_id uuid not null references workspaces(id) on delete
121
+ cascade`, `email citext not null`, `role text not null check (role in
122
+ ('admin','member'))`, `token char(32) not null unique`, `invited_by uuid not null
123
+ references users(id)`, `expires_at timestamptz not null`, `accepted_at timestamptz`,
124
+ `revoked_at timestamptz`, `created_at`.
125
+ 2. Add two indexes in the same trailing block style as `0027`: a unique partial index
126
+ on `(workspace_id, email)` where `accepted_at is null and revoked_at is null`, and
127
+ a plain index on `token`.
128
+ 3. Write the matching down migration.
129
+ 4. In `src/db/schema.ts`, add the `Invitation` type after the `Member` type at line
130
+ 117, and add `invitations` to the `Tables` union at line 146.
131
+
132
+ Done when
133
+ - `npm run migrate:test` applies and rolls back cleanly
134
+ - `npm run typecheck` passes
135
+ - Inserting two pending invitations for the same `(workspace_id, email)` raises a
136
+ unique violation; inserting one after the first is accepted does not
137
+
138
+ ### T-3 · Freeze the invitations API contract
139
+
140
+ Phase 1 · Role api-design · Skill implementer-node · Size s
141
+ Discharges REQ-1, REQ-2, REQ-6
142
+ Depends on T-2 · Parallel with —
143
+
144
+ Files
145
+
146
+ | path | range | action |
147
+ |---|---|---|
148
+ | src/api/contracts/invitations.ts | — | new |
149
+ | src/api/contracts/index.ts | 8-14 | edit |
150
+ | docs/api/invitations.md | — | new |
151
+
152
+ Follow the pattern at
153
+ - `src/api/contracts/members.ts:1-58` — the whole file shape: one `z` schema per
154
+ request and response, `export type X = z.infer<typeof xSchema>` beneath each, and
155
+ the `Errors` const at the bottom listing every error code the endpoints can return.
156
+ - `docs/api/members.md:1-40` — the documentation shape, one section per endpoint.
157
+
158
+ Steps
159
+ 1. Create `src/api/contracts/invitations.ts` with four request/response pairs:
160
+ `CreateInvitation` (in: `email`, `role`; out: `id`, `email`, `role`, `expiresAt`),
161
+ `GetInvitation` (in: `token`; out: `workspaceName`, `email`, `role`, `expiresAt`),
162
+ `AcceptInvitation` (in: `token`; out: `workspaceId`, `membershipId`), and
163
+ `ListInvitations` (out: an array of the `CreateInvitation` response shape).
164
+ 2. Add an `Errors` const in the same style as `members.ts:48-58` with:
165
+ `INVITE_NOT_FOUND`, `INVITE_EXPIRED`, `INVITE_ALREADY_ACCEPTED`, `INVITE_REVOKED`,
166
+ `INVITE_RATE_LIMITED`, `INVITE_ALREADY_MEMBER`.
167
+ 3. Re-export from `src/api/contracts/index.ts`, alphabetically, at line 8-14.
168
+ 4. Write `docs/api/invitations.md` documenting the four endpoints, following the
169
+ members shape.
170
+
171
+ Done when
172
+ - `npm run typecheck` passes
173
+ - `npm run lint` passes
174
+ - Every error code named in the spec's `## Error states` appears in the `Errors` const
175
+
176
+ ---
177
+
178
+ ## Phase 2 · Verification
179
+
180
+ Every assertion in the spec becomes an executable test that **fails**. These live in
181
+ `tests/assertions/` — separate from the co-located unit tests the implementation tasks
182
+ write, so the two never collide and so "how many spec assertions are satisfied" stays a
183
+ number anyone can read off one command.
184
+
185
+ ### T-4 · Assertions A-1..A-11 as failing tests — invitation lifecycle
186
+
187
+ Phase 2 · Role test · Skill test-writer-node · Size m
188
+ Discharges A-1, A-2, A-3, A-4, A-5, A-6, A-7, A-8, A-9, A-10, A-11
189
+ Verification example (A-1..A-6, A-8..A-11), property (A-7)
190
+ Depends on T-3 · Parallel with T-5
191
+
192
+ Files
193
+
194
+ | path | range | action |
195
+ |---|---|---|
196
+ | tests/assertions/invitations.lifecycle.test.ts | — | new |
197
+ | tests/assertions/invitations.token.property.test.ts | — | new |
198
+
199
+ Follow the pattern at
200
+ - `tests/assertions/members.lifecycle.test.ts:1-52` — the assertion-test shape: one
201
+ `describe` per REQ, one `it` per assertion, and the assertion id in the test name so a
202
+ failure output names what is unsatisfied. Copy this exactly.
203
+ - `tests/assertions/helpers.ts:1-40` — `makeWorkspace()`, `makeUser()`, and the
204
+ `truncate` in `afterEach`.
205
+ - `tests/assertions/auth.token.property.test.ts:1-30` — the property-test shape for
206
+ A-7, including the generator and the shrink configuration.
207
+
208
+ Steps
209
+ 1. Create `tests/assertions/invitations.lifecycle.test.ts` with one `describe` per
210
+ requirement REQ-1, REQ-3, REQ-4, REQ-6 and one `it` per assertion, named
211
+ `A-N: <the assertion text from the spec, verbatim>`.
212
+ 2. Write each test against the contract frozen in T-3 — import the request and response
213
+ types, never redeclare a shape.
214
+ 3. For A-7 ("no two invitations in a workspace share a token"), write a property test in
215
+ `invitations.token.property.test.ts`: generate 1,000 tokens, assert distinctness, and
216
+ assert the base32 alphabet and 32-character length hold for every generated value.
217
+ The spec marks A-7 `property` because it is a rule over all inputs, not a case.
218
+ 4. Do not stub the implementation to make anything pass. The imports resolve to modules
219
+ that do not exist yet; that is the expected failure mode at this phase.
220
+
221
+ Done when
222
+ - `npm test -- tests/assertions/invitations` runs and reports **11 failing, 0 passing**
223
+ - Every failure message contains the assertion id it covers
224
+ - `npm run typecheck` still passes — the tests compile against the frozen contract
225
+
226
+ ### T-5 · Assertions A-12..A-17 as failing tests — surfaces and error states
227
+
228
+ Phase 2 · Role test · Skill test-writer-node · Size m
229
+ Discharges A-12, A-13, A-14, A-15, A-16, A-17
230
+ Verification example (A-12..A-16), observation (A-17)
231
+ Depends on T-3 · Parallel with T-4
232
+
233
+ Files
234
+
235
+ | path | range | action |
236
+ |---|---|---|
237
+ | tests/assertions/invitations.api.test.ts | — | new |
238
+ | tests/assertions/invitations.ui.test.tsx | — | new |
239
+
240
+ Follow the pattern at
241
+ - `tests/assertions/members.api.test.ts:1-60` — the request-test shape, including
242
+ `authedAs(admin)` from `test/helpers/auth.ts:18` and how a `403` is asserted.
243
+ - `tests/assertions/password-reset.ui.test.tsx:1-70` — the MSW handler setup, one
244
+ handler per error state.
245
+
246
+ Steps
247
+ 1. Write `invitations.api.test.ts` covering A-12 (an admin can create), A-13 (a
248
+ non-admin gets 403), A-14 (the unauthenticated preview returns exactly four fields),
249
+ and A-15 (accepting twice creates one membership).
250
+ 2. For A-14, assert the **exact key set** of the response, not a subset — the endpoint
251
+ is unauthenticated, so its response body is the whole security surface and a subset
252
+ assertion would not catch a leak.
253
+ 3. Write `invitations.ui.test.tsx` covering A-16: each of the four error codes renders
254
+ its own distinct message, asserted by text.
255
+ 4. A-17 (the accept page is keyboard-navigable and screen-reader-labelled) is marked
256
+ `observation` in the spec — write no test for it here. It is discharged in T-16 step
257
+ 3 with a captured recording. Add a skipped placeholder named `A-17: see T-16` so the
258
+ assertion count stays honest.
259
+
260
+ Done when
261
+ - `npm test -- tests/assertions/invitations` now reports **17 failing, 1 skipped,
262
+ 0 passing** across T-4's and T-5's files
263
+ - The skipped test names T-16 as its discharge
264
+
265
+ ---
266
+
267
+ ## Phase 3 · Core
268
+
269
+ ### T-6 · Implement token generation and validation
270
+
271
+ Phase 3 · Role domain · Skill implementer-node · Size s
272
+ Discharges REQ-2, CL-2
273
+ Depends on T-3 · Parallel with T-7
274
+
275
+ Files
276
+
277
+ | path | range | action |
278
+ |---|---|---|
279
+ | src/invitations/token.ts | — | new |
280
+ | src/invitations/token.test.ts | — | new |
281
+
282
+ Follow the pattern at
283
+ - `src/auth/tokens.ts:14-38` — `generate()` already produces 32-character base32 from
284
+ `crypto.randomBytes`; call it rather than writing a second generator. Its collision
285
+ test at `src/auth/tokens.test.ts:8-22` is the test to copy.
286
+
287
+ Steps
288
+ 1. Create `src/invitations/token.ts` exporting `newInviteToken()` that delegates to
289
+ `generate(32)` from `src/auth/tokens.ts:14`.
290
+ 2. Export `isWellFormed(token: string): boolean` — exactly 32 chars, base32 alphabet
291
+ only. This is a shape check, not an existence check; existence is the service's job.
292
+ 3. Write `src/invitations/token.test.ts`: well-formed tokens pass, wrong length fails,
293
+ non-base32 characters fail, and 10,000 generated tokens are all distinct.
294
+
295
+ Done when
296
+ - `npm test -- invitations/token` passes
297
+ - `edify graph references generate` shows this file among the callers — confirming no
298
+ second generator was written
299
+
300
+ ### T-7 · Implement the invitation service
301
+
302
+ Phase 3 · Role domain · Skill implementer-node · Size m
303
+ Discharges REQ-1, REQ-3, REQ-4, REQ-6
304
+ Depends on T-2, T-3 · Parallel with T-6
305
+
306
+ Files
307
+
308
+ | path | range | action |
309
+ |---|---|---|
310
+ | src/invitations/service.ts | — | new |
311
+ | src/invitations/service.test.ts | — | new |
312
+
313
+ Follow the pattern at
314
+ - `src/members/service.ts:1-140` — the whole service shape: a plain object of async
315
+ functions taking `(db, ...args)` as the first parameter, no class, errors thrown as
316
+ `AppError(Errors.X)` from `src/errors.ts:9`, and transactions via `withTx` from
317
+ `src/db/tx.ts:11`.
318
+ - `src/members/service.test.ts:1-44` — the fixture setup: `makeWorkspace()`,
319
+ `makeUser()`, and the `truncate` in `afterEach`.
320
+
321
+ Steps
322
+ 1. Create `src/invitations/service.ts` exporting four functions:
323
+ `create(db, {workspaceId, email, role, invitedBy})`, `getByToken(db, token)`,
324
+ `accept(db, {token, userId})`, `revoke(db, {id, workspaceId})`.
325
+ 2. `create` — reject with `INVITE_ALREADY_MEMBER` if the email already belongs to a
326
+ member of that workspace (query the existing helper at
327
+ `src/members/service.ts:62`), generate a token with `newInviteToken()`, set
328
+ `expires_at` to `now() + config.invitations.ttlHours`, insert, and return the row.
329
+ 3. `getByToken` — throw `INVITE_NOT_FOUND` when absent, `INVITE_EXPIRED` when
330
+ `expires_at < now()`, `INVITE_ALREADY_ACCEPTED` when `accepted_at` is set,
331
+ `INVITE_REVOKED` when `revoked_at` is set. Check in that order — an expired,
332
+ already-accepted invite reports as accepted, which is the message the spec's
333
+ `## Error states` asks for.
334
+ 4. `accept` — inside `withTx`: re-validate via `getByToken`, insert the membership
335
+ using `members.service.add` at `src/members/service.ts:88`, set `accepted_at`,
336
+ return `{workspaceId, membershipId}`.
337
+ 5. `revoke` — set `revoked_at`; throw `INVITE_NOT_FOUND` if the row is not in the
338
+ given workspace.
339
+ 6. Write `src/invitations/service.test.ts` covering: the happy path for all four
340
+ functions, each of the five error codes, and accepting twice (the second must
341
+ throw `INVITE_ALREADY_ACCEPTED` and must not create a second membership).
342
+
343
+ Done when
344
+ - `npm test -- invitations/service` passes
345
+ - The double-accept test asserts exactly one row in `memberships` afterwards
346
+ - **A-1..A-6 and A-8..A-11 in `tests/assertions/invitations.lifecycle.test.ts` go
347
+ green** — this task is finished when phase 2's red turns green, not when its own unit
348
+ tests pass
349
+
350
+ ---
351
+
352
+ ## Phase 4 · Surfaces
353
+
354
+ All four tasks build against the contract frozen in T-3. Their file sets are disjoint.
355
+
356
+ ### T-8 · POST /workspaces/:id/invitations
357
+
358
+ Phase 4 · Role api · Skill implementer-node · Size s
359
+ Discharges REQ-1
360
+ Depends on T-3, T-7 · Parallel with T-9, T-10, T-11
361
+
362
+ Files
363
+
364
+ | path | range | action |
365
+ |---|---|---|
366
+ | src/api/routes/invitations.create.ts | — | new |
367
+ | src/api/routes/invitations.create.test.ts | — | new |
368
+ | src/api/router.ts | 61-74 | edit |
369
+
370
+ Follow the pattern at
371
+ - `src/api/routes/members.add.ts:1-52` — the exact handler shape: `requireRole('admin')`
372
+ middleware first, contract schema parse, service call, `201` with a `Location`
373
+ header, `AppError` mapped by the shared error middleware.
374
+ - `src/api/routes/members.add.test.ts:1-60` — the request-test shape, including
375
+ `authedAs(admin)` from `test/helpers/auth.ts:18`.
376
+
377
+ Steps
378
+ 1. Create the handler calling `invitations.service.create`, guarded by
379
+ `requireRole('admin')` from `src/api/middleware/role.ts:7`.
380
+ 2. Parse the body with `createInvitationSchema` from the frozen contract. Do not
381
+ redefine the shape.
382
+ 3. Return `201` with the response body and `Location:
383
+ /workspaces/:id/invitations/:inviteId`.
384
+ 4. Register the route in `src/api/router.ts` in the block at lines 61-74, alphabetically
385
+ between `members` and `projects`.
386
+ 5. Write the test: an admin creates one successfully; a non-admin gets `403`; a
387
+ duplicate pending invite gets `409` with `INVITE_ALREADY_MEMBER` or the unique
388
+ violation mapped by `src/api/middleware/errors.ts:31`.
389
+
390
+ Done when
391
+ - `npm test -- invitations.create` passes
392
+ - `curl -X POST` against a dev server with an admin session returns `201` and a
393
+ `Location` header
394
+
395
+ ### T-9 · GET /invitations/:token — the unauthenticated preview
396
+
397
+ Phase 4 · Role api · Skill implementer-node · Size s
398
+ Discharges REQ-2
399
+ Depends on T-3, T-7 · Parallel with T-8, T-10, T-11
400
+
401
+ Files
402
+
403
+ | path | range | action |
404
+ |---|---|---|
405
+ | src/api/routes/invitations.get.ts | — | new |
406
+ | src/api/routes/invitations.get.test.ts | — | new |
407
+ | src/api/router.ts | 61-74 | edit |
408
+ | src/api/middleware/auth.ts | 40-52 | edit |
409
+
410
+ Follow the pattern at
411
+ - `src/api/routes/password-reset.get.ts:1-38` — the only other unauthenticated
412
+ token-lookup endpoint. Same shape, same `publicRoutes` registration, same
413
+ deliberately thin response body.
414
+
415
+ Steps
416
+ 1. Create the handler calling `invitations.service.getByToken`, returning only
417
+ `workspaceName`, `email`, `role`, `expiresAt` — never the inviter's identity or any
418
+ workspace detail beyond the name. This endpoint is unauthenticated; the response
419
+ body is the whole security surface.
420
+ 2. Add the path to the `publicRoutes` array at `src/api/middleware/auth.ts:40-52`,
421
+ beside the password-reset entry.
422
+ 3. Register in `src/api/router.ts` lines 61-74.
423
+ 4. Write the test: a valid token returns the four fields and nothing else (assert the
424
+ exact key set); expired returns `410` with `INVITE_EXPIRED`; unknown returns `404`.
425
+
426
+ Done when
427
+ - `npm test -- invitations.get` passes
428
+ - The response-shape assertion is on the exact key set, not a subset
429
+
430
+ ### T-10 · POST /invitations/:token/accept
431
+
432
+ Phase 4 · Role api · Skill implementer-node · Size s
433
+ Discharges REQ-3
434
+ Depends on T-3, T-7 · Parallel with T-8, T-9, T-11
435
+
436
+ Files
437
+
438
+ | path | range | action |
439
+ |---|---|---|
440
+ | src/api/routes/invitations.accept.ts | — | new |
441
+ | src/api/routes/invitations.accept.test.ts | — | new |
442
+ | src/api/router.ts | 61-74 | edit |
443
+
444
+ Follow the pattern at
445
+ - `src/api/routes/members.add.ts:1-52` — same handler shape, but authenticated as any
446
+ logged-in user rather than role-guarded.
447
+
448
+ Steps
449
+ 1. Create the handler calling `invitations.service.accept` with the session user id
450
+ from `req.user.id`.
451
+ 2. Return `200` with `{workspaceId, membershipId}`.
452
+ 3. Register in `src/api/router.ts` lines 61-74.
453
+ 4. Write the test: accepting while logged in works; accepting while logged out returns
454
+ `401`; accepting an already-accepted invite returns `409`; accepting an invite whose
455
+ email differs from the session user's email still succeeds — the spec's REQ-3 says
456
+ the link is the credential.
457
+
458
+ Done when
459
+ - `npm test -- invitations.accept` passes
460
+ - The already-accepted case asserts exactly one membership row
461
+
462
+ ### T-11 · The invite-accept page
463
+
464
+ Phase 4 · Role frontend · Skill implementer-react · Size m
465
+ Discharges REQ-2, REQ-6
466
+ Depends on T-3 · Parallel with T-8, T-9, T-10
467
+
468
+ Files
469
+
470
+ | path | range | action |
471
+ |---|---|---|
472
+ | web/src/pages/AcceptInvite.tsx | — | new |
473
+ | web/src/pages/AcceptInvite.test.tsx | — | new |
474
+ | web/src/routes.tsx | 28-41 | edit |
475
+
476
+ Follow the pattern at
477
+ - `web/src/pages/ResetPassword.tsx:1-96` — the same token-in-the-URL page: reads the
478
+ token with `useParams`, fetches via `useQuery`, and renders four states in the same
479
+ order — loading, error, ready, submitted. Copy that state machine exactly.
480
+ - `web/src/pages/ResetPassword.test.tsx:1-70` — the MSW handler setup for each state.
481
+
482
+ Steps
483
+ 1. Create the page reading `:token` from the route, fetching `GET /invitations/:token`
484
+ with the generated client at `web/src/api/client.ts:12`.
485
+ 2. Render the four states. For the error state, map each error code from the frozen
486
+ contract to a specific sentence — expired, already accepted, revoked, not found —
487
+ rather than one generic failure message. The spec's `## Error states` names all
488
+ four.
489
+ 3. On accept, call `POST /invitations/:token/accept` and navigate to
490
+ `/workspaces/:workspaceId` on success.
491
+ 4. If the visitor is not logged in, send them to `/login?next=<current path>` — the
492
+ pattern is at `web/src/pages/ResetPassword.tsx:44`.
493
+ 5. Register the route `/invite/:token` in `web/src/routes.tsx` lines 28-41, in the
494
+ public routes block.
495
+ 6. Write the test covering all four error states plus the happy path, with MSW
496
+ handlers per state.
497
+
498
+ Done when
499
+ - `npm test -- AcceptInvite` passes
500
+ - Each of the four error codes renders its own distinct message, asserted by text
501
+
502
+ ---
503
+
504
+ ## Phase 5 · Integration
505
+
506
+ ### T-12 · Send the invitation email
507
+
508
+ Phase 5 · Role integration · Skill implementer-node · Size s
509
+ Discharges REQ-1, REQ-5
510
+ Depends on T-8 · Parallel with —
511
+
512
+ Files
513
+
514
+ | path | range | action |
515
+ |---|---|---|
516
+ | src/email/templates/invitation.tsx | — | new |
517
+ | src/api/routes/invitations.create.ts | 30-46 | edit |
518
+ | src/email/templates/invitation.test.tsx | — | new |
519
+
520
+ Follow the pattern at
521
+ - `src/email/templates/password-reset.tsx:1-64` — the template shape and how the link
522
+ is built from `config.publicUrl`.
523
+ - `src/api/routes/members.add.ts:38-45` — how a route enqueues mail: `mailer.enqueue`,
524
+ never `mailer.send`, so a mail failure never fails the request.
525
+
526
+ Steps
527
+ 1. Create the template taking `{workspaceName, inviterName, acceptUrl, expiresAt}`.
528
+ 2. Build `acceptUrl` as `${config.publicUrl}/invite/${token}` — this must match the
529
+ route registered in T-11 step 5.
530
+ 3. In the create handler, after the service call and before the response, enqueue the
531
+ mail with `mailer.enqueue`.
532
+ 4. Write the template test asserting the rendered link matches the T-11 route exactly.
533
+
534
+ Done when
535
+ - `npm test -- email/invitation` passes
536
+ - Creating an invite in the dev environment puts exactly one message in the outbox
537
+ - A forced mailer failure still returns `201` — the enqueue is not in the request path
538
+
539
+ ### T-13 · End-to-end: invite, open, accept
540
+
541
+ Phase 5 · Role integration · Skill implementer-node · Size m
542
+ Discharges REQ-1, REQ-2, REQ-3
543
+ Depends on T-8, T-9, T-10, T-11, T-12 · Parallel with —
544
+
545
+ Files
546
+
547
+ | path | range | action |
548
+ |---|---|---|
549
+ | e2e/invitations.spec.ts | — | new |
550
+
551
+ Follow the pattern at
552
+ - `e2e/password-reset.spec.ts:1-88` — the full shape: seeded users, the outbox helper
553
+ at `e2e/helpers/outbox.ts:9` for pulling the link out of the sent mail, and the
554
+ `test.describe.serial` wrapper.
555
+
556
+ Steps
557
+ 1. Seed a workspace with an admin and one non-member user.
558
+ 2. As the admin, invite the non-member's email through the UI.
559
+ 3. Read the accept URL out of the outbox with the existing helper.
560
+ 4. Open it as the non-member, accept, and assert landing on the workspace page.
561
+ 5. Assert the members list now shows the new member with the invited role.
562
+ 6. Re-open the same URL and assert the already-accepted message renders.
563
+
564
+ Done when
565
+ - `npm run test:e2e -- invitations` passes twice in a row from a clean database
566
+
567
+ ---
568
+
569
+ ## Phase 6 · Hardening
570
+
571
+ ### T-14 · Rate-limit invitation creation
572
+
573
+ Phase 6 · Role reliability · Skill implementer-node · Size s
574
+ Discharges CL-3
575
+ Depends on T-8 · Parallel with T-15
576
+
577
+ Files
578
+
579
+ | path | range | action |
580
+ |---|---|---|
581
+ | src/api/routes/invitations.create.ts | 12-20 | edit |
582
+ | src/api/routes/invitations.create.test.ts | 60-84 | edit |
583
+
584
+ Follow the pattern at
585
+ - `src/api/middleware/rateLimit.ts:22-40` — the middleware exists; this is a
586
+ registration, not an implementation.
587
+ - `src/api/routes/password-reset.request.ts:14` — an endpoint already applying it,
588
+ keyed per workspace.
589
+
590
+ Steps
591
+ 1. Apply `rateLimit({key: 'workspace', max: config.invitations.maxPerHour, window:
592
+ '1h'})` to the create route, after the role guard and before the handler.
593
+ 2. Add a test that the `maxPerHour + 1`-th request in a window returns `429` with
594
+ `INVITE_RATE_LIMITED`.
595
+
596
+ Done when
597
+ - `npm test -- invitations.create` passes
598
+ - The limit is read from config, not hard-coded — `grep -n '20' src/api/routes/invitations.create.ts` returns nothing
599
+
600
+ ### T-15 · Audit-log every invitation lifecycle event
601
+
602
+ Phase 6 · Role reliability · Skill implementer-node · Size s
603
+ Discharges CL-5
604
+ Depends on T-7 · Parallel with T-14
605
+
606
+ Files
607
+
608
+ | path | range | action |
609
+ |---|---|---|
610
+ | src/invitations/service.ts | 40-160 | edit |
611
+ | src/invitations/service.test.ts | 120-150 | edit |
612
+
613
+ Follow the pattern at
614
+ - `src/members/service.ts:96-104` — `audit.record(db, {actor, action, subject})` called
615
+ inside the same transaction as the change, never after it.
616
+
617
+ Steps
618
+ 1. Add `audit.record` calls inside the existing transactions in `create`, `accept`, and
619
+ `revoke`, with actions `invitation.created`, `invitation.accepted`,
620
+ `invitation.revoked`.
621
+ 2. The subject is the invitation id; the actor is `invitedBy` for create and the
622
+ accepting user for accept.
623
+ 3. Extend the service test to assert one audit row per operation, and that a rolled-back
624
+ transaction leaves none.
625
+
626
+ Done when
627
+ - `npm test -- invitations/service` passes
628
+ - The rollback case asserts zero audit rows
629
+
630
+ ---
631
+
632
+ ## Phase 7 · Proof
633
+
634
+ ### T-16 · Verify the feature
635
+
636
+ Phase 7 · Role verifier · Skill verifier · Size m
637
+ Discharges REQ-1..REQ-6, all CL rows
638
+ Depends on all · Parallel with —
639
+
640
+ **Runs in a fresh session that wrote none of the code.** Nothing below is taken on
641
+ report; every command is re-run and its raw output pasted.
642
+
643
+ Files: none — this task writes evidence, not code.
644
+
645
+ Steps
646
+ 1. Re-run the full suite and paste the raw output: `npm test && npm run test:e2e`. The
647
+ assertion suite is the headline number: `npm test -- tests/assertions/invitations`
648
+ must report **16 passing, 1 skipped, 0 failing** — the seventeen that phase 2 wrote.
649
+ 2. Confirm the ordering with `git log --stat`: every file under `tests/assertions/`
650
+ landed before the source file it exercises. A suite written afterwards encodes the
651
+ behavior the code has rather than the behavior the spec asked for, and this is the
652
+ only way to know which happened.
653
+ 3. Run the feature for real: start the dev stack, invite an address, pull the link from
654
+ the outbox, accept it in a fresh browser profile, and paste the transcript.
655
+ 4. Discharge A-17 / CL-7, the one `observation` assertion: navigate the accept page by
656
+ keyboard only and with a screen reader, and attach the recording. An observation
657
+ without attached evidence is a claim.
658
+ 5. Walk `## Coverage` row by row and mark each satisfied with its evidence, waived with
659
+ its reason, or blocked with what is missing. Check each assertion against the
660
+ verification kind the spec declared for it — a property test that became an example
661
+ test is a silent downgrade and is reported, not accepted.
662
+ 6. Read the whole diff as one design: is there one way of doing each thing, or several?
663
+ Check specifically for a second token generator, a second error-mapping style, and
664
+ inconsistent naming between `invite` and `invitation`.
665
+ 7. Check the spec's `## Open questions` — every one either resolved or restated as a
666
+ standing assumption for the release note.
667
+
668
+ Done when
669
+ - The assertion suite reports 16 passing, 1 skipped, 0 failing, with raw output attached
670
+ - Every `## Coverage` row is satisfied, waived, or explicitly blocked
671
+ - The raw transcript of step 3 and the recording from step 4 are in the report, not
672
+ summaries of them
673
+ - The one-design read is written down with what was checked, not asserted as clean
674
+
675
+ ---
676
+
677
+ ## Coverage
678
+
679
+ | source | what it is | asserted by | built by |
680
+ |---|---|---|---|
681
+ | REQ-1 | An admin can invite someone by email | T-4, T-5 | T-2, T-7, T-8, T-12, T-13 |
682
+ | REQ-2 | The invitee can see who invited them before accepting | T-5 | T-3, T-9, T-11, T-13 |
683
+ | REQ-3 | Accepting the link creates the membership | T-4, T-5 | T-2, T-7, T-10, T-13 |
684
+ | REQ-4 | An admin can revoke a pending invitation | T-4 | T-7 |
685
+ | REQ-5 | The invitee receives an email with the link | T-4 | T-12 |
686
+ | REQ-6 | Expired, used, and revoked links each say what happened | T-4, T-5 | T-3, T-7, T-11 |
687
+ | CL-1 | The feature is behind a flag | — | T-1 |
688
+ | CL-2 | Tokens are unguessable and single-use | T-4 (property) | T-6, T-7 |
689
+ | CL-3 | Invitation creation is rate-limited | T-5 | T-14 |
690
+ | CL-4 | The migration has a rollback | — | T-2 |
691
+ | CL-5 | Lifecycle events are audit-logged | T-4 | T-15 |
692
+ | CL-6 | Personal data has a retention rule | `waived` — the only personal datum is an email address the inviting admin already holds; the row is deleted with the workspace by cascade | |
693
+ | CL-7 | The accept page is accessible | T-5 (skipped placeholder) | `observation` — discharged in T-16 step 4 |
694
+
695
+ Every row filled, checked before the gate. An empty cell means the plan is not ready,
696
+ and this table is the reason "we forgot the permission" becomes a blank cell somebody
697
+ notices in ten seconds rather than an incident.
698
+
699
+ **The `asserted by` column is what makes this verification-first rather than a good
700
+ intention.** A row with a builder and no asserter is a requirement nobody wrote a failing
701
+ test for — it will be built, it will look done, and nothing will ever have proved it. The
702
+ two rows with a dash are legitimately structural (a flag exists or it does not; a down
703
+ migration runs or it does not) and are covered by their tasks' done-checks. Any other
704
+ dash in that column blocks the gate.
705
+
706
+ ## Decisions
707
+
708
+ Empty at the gate. Appended during `/build`; every later spawn carries this section.
709
+
710
+ | # | decision | why | binds |
711
+ |---|---|---|---|
712
+ | D-1 | Accepting an invite whose email differs from the logged-in user's succeeds | T-10 step 4 raised it; the spec's REQ-3 says the link is the credential, and forwarding an invite is a real workflow. Recorded so the hardening phase does not re-close it | T-10, T-13, T-16 |