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
edify/anim.py ADDED
@@ -0,0 +1,499 @@
1
+ """An infinity, drawn while the install works.
2
+
3
+ `edify init` and `edify setup` do real work — extraction, skill install, host
4
+ mirroring — and until now printed nothing while doing it. This is the face of that
5
+ wait, and it is held to the same rules as every other line this CLI writes.
6
+
7
+ **Precomputed frames, not a live plotter** (plan D-3). `dependencies = []` is a hard
8
+ constraint, so there is no curses and no progress-bar library. The frames are a
9
+ tuple of strings built once at import, which also makes the animation *testable* —
10
+ frame count, uniform width, ASCII-safety — rather than something only a human can
11
+ check by squinting at a terminal.
12
+
13
+ **A lemniscate of Gerono** (D-4), `x = cos t`, `y = sin(2t)/2`. It is bounded and
14
+ evenly parameterised, so a head moving at constant `t` moves at roughly constant
15
+ speed on screen. The Bernoulli lemniscate crowds at the origin and reads as a
16
+ stutter, and a rotating unicode spinner is not an infinity at all.
17
+
18
+ **Two glyph sets, chosen by probing the stream** (D-5). `ui.py` already documents
19
+ that a cp1252 Windows console kills a `·`; a command that did its work and then
20
+ died printing its own decoration is the worst of both outcomes.
21
+
22
+ **Decoration is never load-bearing.** Any exception inside the painter disables the
23
+ animation and the command carries on, which is the rule `_invite` already follows
24
+ in `cli.py`. The cursor is restored in a `finally` and again at `atexit`, so a
25
+ Ctrl-C never leaves a headless terminal behind.
26
+ """
27
+
28
+ from __future__ import annotations
29
+
30
+ import atexit
31
+ import math
32
+ import os
33
+ import sys
34
+ import threading
35
+ import time
36
+ from typing import Any
37
+
38
+ from . import ui
39
+
40
+ # -- geometry ---------------------------------------------------------------
41
+
42
+ WIDTH = 31
43
+ HEIGHT = 7
44
+ FRAMES = 48
45
+ #: Samples along the curve. Dense enough that the drawn line has no gaps at this
46
+ #: resolution, which is a property of the grid rather than a number to tune.
47
+ SAMPLES = 480
48
+ #: How many samples behind the head still get the warm glyph. The trail is what
49
+ #: makes the motion readable; without it the head is a dot that appears to
50
+ #: teleport from one arm of the curve to the other.
51
+ TRAIL = 34
52
+
53
+ #: Head, trail, curve. Two sets: what a UTF-8 terminal renders, and what survives
54
+ #: a code page that has never heard of U+00B7.
55
+ UNICODE_GLYPHS = ("●", "○", "·")
56
+ ASCII_GLYPHS = ("O", "o", ".")
57
+
58
+ FPS = 14.0
59
+
60
+ #: How much of a spinner's label is shown. The label says what the wait is for;
61
+ #: past this it is a paragraph, and a terminal narrower than it wraps and breaks
62
+ #: the repaint.
63
+ LABEL = 60
64
+
65
+
66
+ def _point(t: float) -> tuple[float, float]:
67
+ """Gerono at parameter `t`, in [-1, 1] x [-0.5, 0.5]."""
68
+ return math.cos(t), math.sin(2.0 * t) / 2.0
69
+
70
+
71
+ def _cell(t: float) -> tuple[int, int]:
72
+ """One curve point as a grid cell.
73
+
74
+ x spans 2 units across WIDTH columns, y spans 1 unit across HEIGHT rows. The
75
+ halved y in `_point` is the 2:1 aspect correction: a character is about twice
76
+ as tall as it is wide, so an uncorrected plot of a symmetric curve comes out
77
+ as a tall thin bow tie rather than an infinity.
78
+ """
79
+ x, y = _point(t)
80
+ col = int(round((x + 1.0) / 2.0 * (WIDTH - 1)))
81
+ row = int(round((0.5 - y) * (HEIGHT - 1)))
82
+ return max(0, min(HEIGHT - 1, row)), max(0, min(WIDTH - 1, col))
83
+
84
+
85
+ def _build(glyphs: tuple[str, str, str]) -> tuple[str, ...]:
86
+ """The whole animation, as `FRAMES` blocks of `HEIGHT` lines each `WIDTH` wide.
87
+
88
+ Every frame draws the same static curve and moves a bright head along it, so
89
+ the shape never flickers and only the highlight travels.
90
+ """
91
+ head_glyph, warm_glyph, curve_glyph = glyphs
92
+
93
+ curve: list[tuple[int, int]] = []
94
+ seen: set[tuple[int, int]] = set()
95
+ for i in range(SAMPLES):
96
+ t = 2.0 * math.pi * i / SAMPLES
97
+ cell = _cell(t)
98
+ if cell not in seen:
99
+ seen.add(cell)
100
+ curve.append(cell)
101
+
102
+ frames: list[str] = []
103
+ for f in range(FRAMES):
104
+ grid = [[" "] * WIDTH for _ in range(HEIGHT)]
105
+ for row, col in curve:
106
+ grid[row][col] = curve_glyph
107
+
108
+ # Painted tail first, so the head always wins its cell.
109
+ lead = int(SAMPLES * f / FRAMES)
110
+ for back in range(TRAIL, 0, -1):
111
+ row, col = _cell(2.0 * math.pi * ((lead - back) % SAMPLES) / SAMPLES)
112
+ grid[row][col] = warm_glyph
113
+ row, col = _cell(2.0 * math.pi * lead / SAMPLES)
114
+ grid[row][col] = head_glyph
115
+ frames.append("\n".join("".join(row) for row in grid))
116
+ return tuple(frames)
117
+
118
+
119
+ def _tones() -> tuple[dict[tuple[int, int], int], ...]:
120
+ """For every frame, each lit cell's age: 0 is the head, `TRAIL` the oldest.
121
+
122
+ The same walk `_build` makes, kept apart from the glyphs so a frame's text is
123
+ unchanged by colour. The painter reads the age to shade the trail from the
124
+ bright head into the deeper ink, the way a drop thins as it spreads.
125
+ """
126
+ table = []
127
+ for f in range(FRAMES):
128
+ lead = int(SAMPLES * f / FRAMES)
129
+ ages: dict[tuple[int, int], int] = {}
130
+ for back in range(TRAIL, -1, -1):
131
+ ages[_cell(2.0 * math.pi * ((lead - back) % SAMPLES) / SAMPLES)] = back
132
+ table.append(ages)
133
+ return tuple(table)
134
+
135
+
136
+ #: Built once, at import. Two tuples of `FRAMES` strings — deterministic, and so
137
+ #: assertable in a test rather than only visible to a person.
138
+ UNICODE_FRAMES: tuple[str, ...] = _build(UNICODE_GLYPHS)
139
+ ASCII_FRAMES: tuple[str, ...] = _build(ASCII_GLYPHS)
140
+ TONES = _tones()
141
+
142
+ #: The wordmark. Pure ASCII by construction, because it survives a pipe, a CI log,
143
+ #: and a code page — it is printed even when the animation is not.
144
+ BANNER = (
145
+ " ___ ___ ___ ___ __ __",
146
+ " | __| \\_ _| __|\\ \\ / / the infinite loop, made finite",
147
+ " | _|| |) | || _| \\ V / three documents and a map",
148
+ " |___|___/___|_| |_|",
149
+ )
150
+
151
+ #: The wordmark a person at a terminal sees: the site's heavy sans, in half blocks.
152
+ #: Three rows, so it is a mark and not a poster.
153
+ WORDMARK = (
154
+ "█▀▀▀ █▀▀▄ █ █▀▀▀ █ █",
155
+ "█▀▀ █ █ █ █▀▀ ▀█▀ ",
156
+ "▀▀▀▀ ▀▀▀ ▀ ▀ ▀ ",
157
+ )
158
+
159
+ #: The readout under the wordmark, as wide as the clips' corner readouts sit apart.
160
+ READOUT_WIDTH = 46
161
+
162
+ #: The ink pool. Where it comes to rest (a column of the wordmark), how wide it is
163
+ #: on each row — uneven, so it reads as liquid and not as a highlighter — and how
164
+ #: long it takes to arrive: `--d-el`, the site's single-element entrance.
165
+ POOL_REST = 9.0
166
+ POOL_HALF = (4.5, 5.5, 3.5)
167
+ POOL_MS = 420
168
+ POOL_FRAMES = 12
169
+
170
+
171
+ # -- glyph selection --------------------------------------------------------
172
+
173
+
174
+ def frames_for(stream: Any = None) -> tuple[str, ...]:
175
+ """The frame table this stream can actually print.
176
+
177
+ Probes `stream.encoding` rather than assuming, mirroring the degradation
178
+ `ui._emit` already performs. A stream with no encoding, or one that cannot
179
+ round-trip the glyphs, gets the ASCII table.
180
+ """
181
+ stream = stream if stream is not None else sys.stderr
182
+ encoding = getattr(stream, "encoding", None)
183
+ if not encoding:
184
+ return ASCII_FRAMES
185
+ try:
186
+ "".join(UNICODE_GLYPHS).encode(encoding)
187
+ except (UnicodeEncodeError, LookupError, TypeError):
188
+ return ASCII_FRAMES
189
+ return UNICODE_FRAMES
190
+
191
+
192
+ # -- terminal control -------------------------------------------------------
193
+
194
+ _HIDE = "\033[?25l"
195
+ _SHOW = "\033[?25h"
196
+ _UP = "\033[F"
197
+ _CLEAR_LINE = "\033[2K"
198
+
199
+ #: Set the first time a painter hides the cursor. The `atexit` backstop checks it,
200
+ #: so a run that never animated — every test, every pipe, every CI job — does not
201
+ #: emit a stray escape sequence into somebody's captured output.
202
+ _hid_cursor = False
203
+
204
+
205
+ def _restore_cursor() -> None:
206
+ """The backstop. Registered at `atexit` so a hard exit still shows a cursor."""
207
+ global _hid_cursor
208
+ if not _hid_cursor:
209
+ return
210
+ _hid_cursor = False
211
+ try:
212
+ sys.stderr.write(_SHOW)
213
+ sys.stderr.flush()
214
+ except (OSError, ValueError):
215
+ pass
216
+
217
+
218
+ atexit.register(_restore_cursor)
219
+
220
+
221
+ # -- the spinner ------------------------------------------------------------
222
+
223
+
224
+ class Spinner:
225
+ """Paint the infinity to stderr while the block runs. A context manager.
226
+
227
+ stderr, not stdout: `--json` output and every piped answer stay clean by
228
+ construction rather than by remembering. The thread is a daemon, so an
229
+ interpreter that is shutting down is never held open by decoration.
230
+
231
+ Whether it paints at all is `Out.animated` — the one place tty, `--json`,
232
+ `--quiet`, `--no-anim`, `EDIFY_NO_ANIM`, `CI` and `TERM=dumb` are decided,
233
+ next to the existing `Out.interactive`. When it does not paint, the label is
234
+ still printed as one static line, so a pipe and a CI log say what happened.
235
+ """
236
+
237
+ def __init__(self, out: Any, label: str = "", stream: Any = None) -> None:
238
+ self.out = out
239
+ self.label = label
240
+ self.stream = stream if stream is not None else sys.stderr
241
+ self._thread: threading.Thread | None = None
242
+ self._stop = threading.Event()
243
+ self._painted = False
244
+ self._start = time.monotonic()
245
+ self._lines = HEIGHT + (1 if label else 0)
246
+
247
+ # -- lifecycle ---------------------------------------------------
248
+
249
+ def __enter__(self) -> "Spinner":
250
+ self._start = time.monotonic()
251
+ if not self._enabled():
252
+ if self.label:
253
+ self.out.note(self.label)
254
+ return self
255
+ try:
256
+ self._thread = threading.Thread(target=self._paint, daemon=True)
257
+ self._thread.start()
258
+ except RuntimeError:
259
+ # No threads available. Not a reason for the command to fail.
260
+ self._thread = None
261
+ if self.label:
262
+ self.out.note(self.label)
263
+ return self
264
+
265
+ def __exit__(self, *exc: Any) -> bool:
266
+ self._stop.set()
267
+ thread, self._thread = self._thread, None
268
+ if thread is not None:
269
+ thread.join(timeout=1.0)
270
+ self._erase()
271
+ return False # never swallow the block's exception
272
+
273
+ # -- internals ---------------------------------------------------
274
+
275
+ def _enabled(self) -> bool:
276
+ return bool(getattr(self.out, "animated", False))
277
+
278
+ def _paint(self) -> None:
279
+ """The painter. Every failure here disables the animation, silently."""
280
+ global _hid_cursor
281
+ frames = frames_for(self.stream)
282
+ try:
283
+ # The `atexit` backstop writes to the real stderr, so it only arms when
284
+ # that is the stream being painted. A spinner pointed somewhere else
285
+ # cleans up in its own `finally` and leaves the real terminal alone.
286
+ if self.stream is sys.stderr:
287
+ _hid_cursor = True
288
+ self.stream.write(_HIDE)
289
+ index = 0
290
+ while not self._stop.is_set():
291
+ self._write_frame(frames[index % len(frames)], index % len(frames))
292
+ index += 1
293
+ self._stop.wait(1.0 / FPS)
294
+ except Exception: # noqa: BLE001 — decoration is never load-bearing
295
+ self._stop.set()
296
+ finally:
297
+ try:
298
+ self.stream.write(_SHOW)
299
+ self.stream.flush()
300
+ except Exception: # noqa: BLE001
301
+ pass
302
+
303
+ def _write_frame(self, frame: str, index: int = 0) -> None:
304
+ colour = bool(getattr(self.out, "color_err", False))
305
+ body = "\n".join(" " + row for row in inked(frame, index, colour).split("\n"))
306
+ if self.label:
307
+ # The clips carry a readout in their corners; the wait carries one too.
308
+ took = f"{time.monotonic() - self._start:4.1f}s"
309
+ said = f" {self.label[:LABEL]} {took}"
310
+ if colour:
311
+ said = f" {ui.sgr('muted')}{self.label[:LABEL]}{ui.RESET} {ui.sgr('faint')}{took}{ui.RESET}"
312
+ body = body + "\n" + said
313
+ if self._painted:
314
+ self.stream.write(_UP * self._lines)
315
+ chunks = []
316
+ for line in body.split("\n"):
317
+ chunks.append(_CLEAR_LINE + line + "\n")
318
+ self.stream.write("".join(chunks))
319
+ self.stream.flush()
320
+ self._painted = True
321
+
322
+ def _erase(self) -> None:
323
+ """Take the region back off the screen and restore the cursor.
324
+
325
+ In a `finally` on purpose: an exception in the wrapped block must not be
326
+ the reason somebody's terminal has no cursor for the rest of the day.
327
+ """
328
+ if not self._painted:
329
+ return
330
+ self._painted = False
331
+ try:
332
+ self.stream.write(_UP * self._lines)
333
+ for _ in range(self._lines):
334
+ self.stream.write(_CLEAR_LINE + "\n")
335
+ self.stream.write(_UP * self._lines)
336
+ self.stream.write(_SHOW)
337
+ self.stream.flush()
338
+ except Exception: # noqa: BLE001
339
+ pass
340
+
341
+
342
+ class NullSpinner:
343
+ """What a caller gets when it wants the shape without the animation."""
344
+
345
+ def __enter__(self) -> "NullSpinner":
346
+ return self
347
+
348
+ def __exit__(self, *exc: Any) -> bool:
349
+ return False
350
+
351
+
352
+ def spinner(out: Any, label: str = "") -> Any:
353
+ """The one call site every command uses. Always safe, always a context manager."""
354
+ try:
355
+ return Spinner(out, label)
356
+ except Exception: # noqa: BLE001 — decoration is never load-bearing
357
+ return NullSpinner()
358
+
359
+
360
+ # -- the banner -------------------------------------------------------------
361
+
362
+
363
+ def banner(out: Any, verb: str = "init") -> None:
364
+ """The wordmark, once, as the install opens.
365
+
366
+ Suppressed only by `--json` and `--quiet` — not by the absence of a tty. Off a
367
+ terminal it is the static ASCII `BANNER`, so it survives a pipe and reads fine
368
+ in a CI log, and a build log that says which tool wrote it is more useful than
369
+ one that does not. At a terminal it is the site's wordmark, and the ink pours
370
+ into it once.
371
+ """
372
+ if getattr(out, "json_mode", False) or getattr(out, "quiet", False):
373
+ return
374
+ if os.environ.get("EDIFY_NO_ANIM"):
375
+ return
376
+ if getattr(out, "no_anim", False):
377
+ return
378
+ try:
379
+ if getattr(out, "animated", False) and ui.encodes("█▀▄─", sys.stderr):
380
+ _wordmark(out, verb)
381
+ return
382
+ for line in BANNER:
383
+ out.note(line)
384
+ out.note("")
385
+ except Exception: # noqa: BLE001
386
+ pass
387
+
388
+
389
+ def _ease(t: float) -> float:
390
+ """`--e-edify`, cubic-bezier(.2,.8,.2,1), closely enough for twelve frames."""
391
+ return 1.0 - (1.0 - t) ** 3
392
+
393
+
394
+ def _mix(a: tuple[int, int, int], b: tuple[int, int, int], t: float) -> tuple[int, int, int]:
395
+ return tuple(round(a[i] + (b[i] - a[i]) * t) for i in range(3)) # type: ignore[return-value]
396
+
397
+
398
+ def ink(row: int, line: str, centre: float, colour: bool) -> str:
399
+ """One row of the wordmark with the pool at `centre`.
400
+
401
+ Inside the pool a glyph takes the ink: bright at the heart, the deeper edge
402
+ blue at the rim. Outside it keeps the terminal's own foreground — flat is the
403
+ agent alone, the ink is EDIFY. A 16-colour terminal gets one blue.
404
+ """
405
+ if not colour:
406
+ return line
407
+ palette = ui.PALETTES[ui.theme()]
408
+ bright, edge = ui.rgb(palette["signal"]), ui.rgb(palette["edge"])
409
+ bits = ui.depth()
410
+ half = POOL_HALF[row % len(POOL_HALF)]
411
+ cells = []
412
+ for col, glyph in enumerate(line):
413
+ reach = abs(col - centre) / half
414
+ if glyph == " " or reach > 1.0:
415
+ cells.append(glyph)
416
+ continue
417
+ start = "\033[94m" if bits == 16 else ui.fg(_mix(bright, edge, reach ** 1.6), bits)
418
+ cells.append(start + glyph + ui.RESET)
419
+ return "".join(cells)
420
+
421
+
422
+ def inked(frame: str, index: int, colour: bool) -> str:
423
+ """A frame of the infinity in ink: the head bright, the trail thinning into the
424
+ deeper blue, the curve at rest in the faint tone. Text unchanged without colour."""
425
+ if not colour:
426
+ return frame
427
+ palette = ui.PALETTES[ui.theme()]
428
+ bright, edge = ui.rgb(palette["signal"]), ui.rgb(palette["edge"])
429
+ faint, bits = ui.sgr("faint"), ui.depth()
430
+ ages = TONES[index % len(TONES)]
431
+ rows = []
432
+ for r, row in enumerate(frame.split("\n")):
433
+ cells = []
434
+ for c, glyph in enumerate(row):
435
+ if glyph == " ":
436
+ cells.append(glyph)
437
+ continue
438
+ age = ages.get((r, c))
439
+ if age is None:
440
+ start = faint
441
+ elif bits == 16:
442
+ start = "\033[94m" if age == 0 else "\033[34m"
443
+ else:
444
+ start = ui.fg(_mix(bright, edge, age / TRAIL), bits)
445
+ cells.append(start + glyph + ui.RESET)
446
+ rows.append("".join(cells))
447
+ return "\n".join(rows)
448
+
449
+
450
+ def readout(verb: str, colour: bool, width: int = READOUT_WIDTH) -> str:
451
+ """`EDIFY / INIT ──────── 0.2.0` — the clips' corner readout, as one line."""
452
+ from . import __version__
453
+
454
+ left, right = f"EDIFY / {verb.upper()}", __version__
455
+ rule = "─" * max(3, width - len(left) - len(right) - 2)
456
+ if not colour:
457
+ return f"{left} {rule} {right}"
458
+ muted, faint = ui.sgr("muted"), ui.sgr("faint")
459
+ return f"{muted}{left}{ui.RESET} {faint}{rule}{ui.RESET} {muted}{right}{ui.RESET}"
460
+
461
+
462
+ def _wordmark(out: Any, verb: str) -> None:
463
+ """Paint the wordmark to stderr, pour the ink once, and leave it standing."""
464
+ stream = sys.stderr
465
+ colour = bool(getattr(out, "color_err", False))
466
+ pad = " "
467
+ rows = len(WORDMARK)
468
+ tail = [readout(verb, colour), ui.sgr("muted") + "three documents and a map" + ui.RESET if colour
469
+ else "three documents and a map", ""]
470
+
471
+ def paint(centre: float, first: bool) -> None:
472
+ if not first:
473
+ stream.write(_UP * rows)
474
+ stream.write("".join(
475
+ _CLEAR_LINE + pad + ink(r, WORDMARK[r], centre, colour) + "\n" for r in range(rows)
476
+ ))
477
+ stream.flush()
478
+
479
+ if colour:
480
+ start = -max(POOL_HALF) - 1.0
481
+ stream.write(_HIDE)
482
+ try:
483
+ for f in range(POOL_FRAMES + 1):
484
+ centre = start + (POOL_REST - start) * _ease(f / POOL_FRAMES)
485
+ paint(centre, first=f == 0)
486
+ if f < POOL_FRAMES:
487
+ time.sleep(POOL_MS / 1000.0 / POOL_FRAMES)
488
+ finally:
489
+ stream.write(_SHOW)
490
+ else:
491
+ paint(POOL_REST, first=True)
492
+ for line in tail:
493
+ stream.write(pad + line + "\n" if line else "\n")
494
+ stream.flush()
495
+
496
+
497
+ def elapsed(start: float) -> str:
498
+ """`2.4s` — what a spinner was covering for, said once after it stops."""
499
+ return f"{max(0.0, time.monotonic() - start):.1f}s"
@@ -0,0 +1,64 @@
1
+ ---
2
+ name: build
3
+ description: A plan becomes working software.
4
+ model: cheapest that follows written instructions
5
+ ends-at: a diff and a green suite
6
+ ---
7
+
8
+ # /build
9
+
10
+ Execute the whole task list in one run, phases in order. This command does not
11
+ plan, does not choose, does not research, and does not improvise.
12
+
13
+ ## What you read
14
+
15
+ The approved `tasks.md`. That is the only input. The spec and the plan are
16
+ deliberately withheld: a builder with access to the reasoning behind the plan has
17
+ judgment again, and judgment at build time is the one thing the executor is defined
18
+ by not having.
19
+
20
+ ## What you write
21
+
22
+ Code, and the `## Decisions` section of `tasks.md`.
23
+
24
+ ## The run
25
+
26
+ ```
27
+ for each phase in order:
28
+ for each parallel-safe group in the phase:
29
+ spawn one agent per task
30
+ payload: skill file + task block + ## Decisions
31
+ servers: edify mcp for <role> <phase> # usually zero or one
32
+ run the phase exit check
33
+ edify graph update <the directories that changed>
34
+ append any forced decision to ## Decisions
35
+ ```
36
+
37
+ Resolve the skill with `edify skills resolve <role> <phase>` — one lookup, one
38
+ line, one file path. Never browse the skills directory to decide.
39
+
40
+ Phase 2 ends with the suite entirely red. That is the correct state and the target
41
+ every later phase is measured against. Phase 7 is `/verify` in a fresh agent that
42
+ wrote none of the code.
43
+
44
+ ## The three rules that define this executor
45
+
46
+ - **It does not plan.** No restructuring, no "while I'm here", no better idea.
47
+ - **It does not explore.** The task says where; the graph answers structure; the
48
+ docs server answers library questions. If none of the three has the answer, the
49
+ plan was incomplete and that is a finding, not a gap to fill with judgment.
50
+ - **It does not adapt.** A task that cannot be done as written stops, writes one
51
+ blocker line, and the run continues with independent tasks.
52
+
53
+ ## On failure
54
+
55
+ A failed done-check is retried once. On the second failure the debugger runs with
56
+ the accumulated evidence. On the third the task is marked blocked and the run
57
+ continues on tasks that do not depend on it. A blocked task at the end of a run is
58
+ a `/tasks` amendment — a normal Tuesday, not a crisis.
59
+
60
+ ## What this command refuses
61
+
62
+ Running against an unapproved plan. Running phases out of order. Editing a contract
63
+ frozen at the end of phase 1. Making a design decision the plan left open without
64
+ recording it in `## Decisions`. Declaring a task done without its check passing.
@@ -0,0 +1,68 @@
1
+ ---
2
+ name: plan
3
+ description: A specification becomes technical decisions and a sequence.
4
+ model: strongest
5
+ ends-at: a human
6
+ ---
7
+
8
+ # /plan
9
+
10
+ Make every decision that binds more than one task, once, so that no task has to
11
+ make one. Skipped for most features, and skipping it is the normal case.
12
+
13
+ ## When this runs at all
14
+
15
+ Write a plan when any of these is true: the feature introduces a technology,
16
+ library, or external service this repository does not already use; it spans more
17
+ than one milestone or shippable stage; it needs cross-cutting strategy — a
18
+ migration sequence, a build variant, a bundled asset, a shared component, a config
19
+ surface; or more than one person will build parts of it.
20
+
21
+ Otherwise go straight from `/spec` to `/tasks`. A one-page plan is ceremony, and a
22
+ repository whose plans are all one page should stop writing them.
23
+
24
+ ## What you read
25
+
26
+ The approved `spec.md`, and the graph. Nothing else.
27
+
28
+ ## What you write
29
+
30
+ `specs/<feature>/plan.md`, in the format at `.edify/formats/plan.format.md`.
31
+
32
+ ## The passes
33
+
34
+ 1. **Cut into milestones** by dependency, and write each dependency rule with its
35
+ reason. `/tasks` relaxes rules when a plan is amended and cannot do that safely
36
+ without knowing why each one exists.
37
+ 2. **Decide the technology.** Each row names the alternative it beat and an exact
38
+ version — `2.3`, not `^2.3` and not `latest`. A row with no alternative is a
39
+ default, and should say so rather than being dressed as a decision; a default is
40
+ much cheaper to revisit six months later.
41
+ 3. **Write the cross-cutting strategy.** Migration numbers allocated once here so
42
+ two tasks never claim the same one. Build variants. Bundled assets with a size
43
+ budget stated rather than discovered. Shared components named so three later
44
+ milestones do not each build their own. And the verification budget for any
45
+ assertion the spec marks above `property` on the ladder.
46
+ 4. **Resolve the context seeds** — per milestone, `(file, line-start, line-end,
47
+ why)` resolved against the graph, so `/tasks` inherits them instead of
48
+ re-deriving them. A seed without a line range transfers its cost downstream,
49
+ which is the whole thing this document exists to prevent.
50
+ 5. **Map the risks**, each to the milestone that mitigates it. A risk with no
51
+ mitigation has been noticed rather than handled, and the row should say that
52
+ rather than looking handled.
53
+
54
+ Run `edify check` before the gate.
55
+
56
+ ## What this command refuses
57
+
58
+ Specifying function signatures or data structures beyond the contracts — that is
59
+ `/tasks`, which has the graph queries to make them accurate. A technology row with
60
+ no exact version. A context seed with no line range. Carrying dates: sizes and
61
+ sequences, never a schedule.
62
+
63
+ ## The gate
64
+
65
+ Show the human the milestone sequence, the decisions with their alternatives, and
66
+ the risks. This is where an architectural disagreement is cheap.
67
+
68
+ Format: `.edify/formats/plan.format.md` · Example: `.edify/formats/plan.example.md`
@@ -0,0 +1,63 @@
1
+ ---
2
+ name: spec
3
+ description: A brief becomes a specification.
4
+ model: strongest
5
+ ends-at: a human
6
+ ---
7
+
8
+ # /spec
9
+
10
+ Turn a couple of sentences into a specification a non-engineer can read and a
11
+ planner can build from. A mistake here is paid for again on every task downstream,
12
+ so this is the slow, expensive command and it is meant to be.
13
+
14
+ ## What you read
15
+
16
+ The brief — whatever the person typed, or the file they pointed at. The graph, for
17
+ every claim about this codebase. The existing `specs/<feature>/spec.md` if you are
18
+ amending one. Not the codebase directly: `edify graph where`, `edify graph
19
+ dependents`, and `edify graph defines` answer structural questions exactly, and
20
+ exploring produces a slightly different answer every session.
21
+
22
+ ## What you write
23
+
24
+ `specs/<feature>/spec.md`, in the format at `.edify/formats/spec.format.md`. The
25
+ worked example beside it is the calibration — read it before writing the first one.
26
+
27
+ ## The loop, bounded at three passes
28
+
29
+ 1. Capture the brief verbatim into `## Brief`. Never edit it afterwards. It is the
30
+ only uncontaminated statement of intent in the system, and both the adversary
31
+ and the final review check the result against it rather than against the draft
32
+ that grew out of it.
33
+ 2. Draft the intent clauses, the constraints, the requirements, the assertions, and
34
+ the non-goals. Every claim about the codebase comes from a graph query.
35
+ 3. Launch one adversary — a separate agent given only the brief and the finished
36
+ draft, never your reasoning. Its question is: what does this feature entail that
37
+ nobody asked for and the draft did not catch? Its findings append to
38
+ `## What this entails` and `## Open questions`, marked adversary-found.
39
+ 4. Re-read the draft against the brief. Every intent clause served by at least one
40
+ requirement, every requirement by at least one assertion, every assertion
41
+ carrying a verification kind from the ladder.
42
+ 5. Stop when a pass finds nothing new, or at three passes. Hitting the bound is
43
+ information: the brief is genuinely ambiguous, and the residue goes into
44
+ `## Open questions` where a human sees it rather than into more token spend.
45
+
46
+ Run `edify check` before showing anyone the result.
47
+
48
+ ## What this command refuses
49
+
50
+ Writing application code. A requirement with no assertion. An assertion that cannot
51
+ fail, or that carries no verification kind. Skipping the adversary because the
52
+ feature looks simple. A citation that is a bare filename rather than `file:line` or
53
+ the literal `new`. Naming a specific library or version — that is a decision, and
54
+ decisions belong to `/plan`.
55
+
56
+ ## The gate
57
+
58
+ Show the human: the intent, the requirements, the closure checklist with open rows
59
+ highlighted, the open questions, and a rough cost band. They resolve the questions
60
+ or accept the defaults on the record, and approve. Five minutes, once per feature,
61
+ and it is the step that stops a beautifully built wrong thing.
62
+
63
+ Format: `.edify/formats/spec.format.md` · Example: `.edify/formats/spec.example.md`