Third read: SPECs match the code, contract written out

[suleimansh]

One more read of both packages, this time by an agent with no memory of the earlier passes, and I checked each of its claims against the code before taking it. What survived: two SPEC sentences that contradict the code, one .d.ts comment that misdescribes a field, a test SPEC describing The Framework's git calls as the package's, the last definite "the daemon / the sweep / the panel" mentions, a word ("hand-off") both packages use and neither defined, and the GitHub Actions workflow contract that a stranger had to read actions.ts to learn. Text only; no behaviour changes.

---

🤖 curated · Fable 5, effort high

• agent-driver/src/types.SPEC.md: "reading a file … only when that workspace is on this machine" — the GitHub Actions driver reads from the pushed branch; the sentence now says "only by a driver that can still reach that workspace — from disk, or from the branch a runner pushed".
• agent-driver/src/types.ts (DriverSession.id): "the agent's own session id when it exposes one" — no driver does that; it is the id the driver mints, and the CLI's own id is DriverTurn.sessionId. Said so.
• agent-driver/src/actions.SPEC.md + the workflow option doc: the workflow contract is now written out — inputs prompt, correlation_id, branch, model, resume_session_id; the id in the run name; an artifact named after it with execution.json and meta.json { branch }. The "no artifact" error no longer names a "collect step" the package doesn't ship.
• agent-driver/SPEC.md, types.SPEC.md: glossary entry for hand-off / anchor; skill-branches says "whether the caller allows a push" and "the commit a cloud session pushed" instead of "handoff"/"hand-off anchor".
• skill-branches/src/git.test.SPEC.md + git.test.ts: the budget test covers what a caller may run through the runner, not "each real git command the package runs" (the list was our call sites, agent-data included; it's topic now).
• skill-branches/src/worktree.ts, worktree.SPEC.md, cli.SPEC.md: "the daemon only holds its pid", "what the sweep asks", "the sweep read an agent's branch", "cost the panel it sits in", "the daemon uses" → a caller, a reclaim pass, the listing, a daemon.
• Plan codes and notes from the old home dropped: (E5), (B5), (D5) in worktree.ts, reclaim.ts, reclaim.test.ts, types.ts; "legacy slash-named" / "pre-Avoid / (and other FS problematic chars) in branch names #1581" in branch-links.*; "same gotcha as enumerateGitRepos in install.ts" in worktree.test.ts; "Consumption limits #519 was specced against a daily limit" in types.ts / types.SPEC.md.

Left alone: the DriverImplId closed list with claude-web, and sessionLink/anchorSha on the result event (the contract for the outside driver, by design); SKILL.md's "publishing … is done for you" (what the skill tells the agent is design); indefinite "a daemon"/"a dashboard" as example callers; history narration in driver doc comments and product words in test comments (code-level).

Proof: pnpm -r typecheck clean; skill-branches 117/117, agent-driver 79/79, framework 1471/1471 green in a fresh worktree off 4458f288.