From cbbb168e7cb2e3ce1c2ab1ebe23685c3293dc6a2 Mon Sep 17 00:00:00 2001 From: Gabriel Brown Date: Fri, 10 Jul 2026 17:54:06 -0400 Subject: [PATCH] docs: add implementation handoff for Claude --- docs/superpowers/CLAUDE-HANDOFF-2026-07-10.md | 202 ++++++++++++++++++ 1 file changed, 202 insertions(+) create mode 100644 docs/superpowers/CLAUDE-HANDOFF-2026-07-10.md diff --git a/docs/superpowers/CLAUDE-HANDOFF-2026-07-10.md b/docs/superpowers/CLAUDE-HANDOFF-2026-07-10.md new file mode 100644 index 0000000..2e914ee --- /dev/null +++ b/docs/superpowers/CLAUDE-HANDOFF-2026-07-10.md @@ -0,0 +1,202 @@ +# Spoon implementation handoff for Claude + +## Objective + +Continue and complete every task in the five plans indexed by +`docs/superpowers/plans/2026-07-10-spoon-implementation-plan-index.md`. +The plans contain 63 tasks and must be executed in phase order. Use the +project `AGENTS.md`, test-first implementation, a task-scoped review after +each task, and a whole-branch review at the end. + +## Canonical workspace + +- Integration worktree: `/home/gib/.codex/worktrees/Spoon/spoon-stabilize-unify-build` +- Integration branch: `codex/spoon-stabilize-unify-build` +- Current integration HEAD before this handoff commit: `8af33fc` +- Original checkout: `/home/gib/Documents/Code/Spoon`, still on `main` at + `8aa9140`. Do not implement in the original checkout. +- `main` was already two commits ahead of `origin/main` when work began. + Preserve it and the original checkout's untracked `.agents/` directory. + +## Current state + +Phase 1 Tasks 1-5 and 7-13 are implemented, independently reviewed, fixed +where required, integrated, and verified with focused static/unit checks. +The durable scratch ledger is +`/home/gib/.codex/worktrees/Spoon/spoon-stabilize-unify-build/.superpowers/sdd/progress.md`. + +Integrated Phase 1 commits, newest first: + +```text +8af33fc fix(worker): always release stopped workspaces +00f96a1 fix(agent-jobs): close maintenance jobs after decision +1e1435e fix(agent-jobs): recover failed claim decryption +cf45404 fix(agent-jobs): validate claims before claiming +926008f fix(workspace): skip queries for missing jobs +2beeeb1 fix(app): handle nullable detail consumers +ed21126 fix(app): add friendly not-found handling +c4d0f52 fix(terminal): use real TTY exec and resize +906f906 fix(backend): use generated import extension +bdb2964 fix(sync): honor per-spoon auto-sync settings +57c175a fix(worker): contain workspace paths against symlinks +2bc090c chore: remove terminal task scratch report +d4a3856 fix(workspace): key shell by job +020ffbf fix(worker-auth): unify token checks and bind job environment +feb3723 fix(terminal): preserve animation-frame first fit +75d0639 fix(terminal): refit after fonts load +0b5a2c0 fix(worker): ensure reconciled boxes before acquire +284f7ea fix(worker): serialize box failure and idle reaping +490c053 chore: remove implementation scratch report +0a4461e fix(agent-jobs): prevent terminal status resurrection +9e7a872 fix(worker): make user-box lifecycle concurrency-safe +daec4d6 fix(worker): make workspace cleanup layout-aware +``` + +## Immediate next action: finish Phase 1 Task 6 + +Task 6 is complete on its isolated branch/worktree but has not had its final +post-fix review and has not been integrated. + +- Worktree: `/home/gib/.codex/worktrees/Spoon/phase1-task6` +- Branch: `codex/phase1-task6` +- Commits to review and integrate: + - `bdebacc fix(agent-jobs): add heartbeat cancel and stale recovery` + - `233032a fix(worker): make cancellation teardown failure-safe` +- Report: `/tmp/spoon-phase1-task6-report.md` +- Requirements brief: + `/home/gib/.codex/worktrees/Spoon/spoon-stabilize-unify-build/.superpowers/sdd/task-6-brief.md` + +The first review found that Codex was not actually killed on cancellation and +that fallible event/status operations could bypass timer and ownership cleanup. +Commit `233032a` addresses those findings with: + +- a job-specific in-box Codex process session; +- PID plus `/proc//environ` marker validation before isolated TERM/KILL; +- serialized heartbeat cancellation so ticks cannot overlap; +- failure-safe explicit stop, draft-PR, cancellation, and claim-failure cleanup; +- worker regressions for Codex kill, duplicate ticks, and teardown rejection; +- expanded backend stale-recovery matrix tests. + +Reported checks on that exact branch: worker format/lint/typecheck and 51/51 +unit tests pass; backend 47/47 unit tests pass; stale-recovery matrix 8/8. +The timeout-not-requeue policy is explicitly documented as the plan's deliberate +deferral. Live Docker/Podman isolation remains untested. + +Resume sequence: + +1. Dispatch a fresh read-only reviewer for Task 6 over both commits and the + updated report. Recheck the two prior findings, job-specific kill safety, + timer serialization, all teardown paths, recovery thresholds/statuses, and + tests. +2. Fix and re-review any Critical/Important finding. +3. Cherry-pick `bdebacc` and `233032a` into the integration worktree. Expect + possible conflicts in `worker.ts` and `agentJobs.ts` because Task 7 was + integrated afterward. Preserve Task 7's `finally`-based workspace release + semantics while retaining Task 6's heartbeat cleanup. +4. Run fresh integrated worker focused/full tests and typecheck; run backend + focused tests using the generated-file workaround below. +5. Append Task 6 to `.superpowers/sdd/progress.md`, mark Phase 1 complete, and + perform a broad Phase 1 review before starting Phase 2. + +## Remaining work + +After Task 6, implement all tasks in these plans in order: + +1. `docs/superpowers/plans/2026-07-10-spoon-phase2-runtime-unification.md` + — 12 tasks. +2. `docs/superpowers/plans/2026-07-10-spoon-phase3-dev-box-surface.md` + — 11 tasks. +3. `docs/superpowers/plans/2026-07-10-spoon-phase4-sync-correctness.md` + — 12 tasks. +4. `docs/superpowers/plans/2026-07-10-spoon-phase5-notifications-polish.md` + — 15 tasks. + +The Phase 2 plan has been preflight-read and no conflict with the implemented +Phase 1 APIs was identified. Do not overwrite Phase 1 task briefs in +`.superpowers/sdd/` until Task 6 is fully reviewed and integrated; the +`task-brief` helper uses generic task numbers. + +## Required execution/review workflow + +- Use a fresh implementer per task and a fresh task-scoped reviewer after each + task. Fix all Critical and Important findings, then re-review. +- Isolate concurrent tasks in separate worktrees/branches. Never let agents + commit concurrently in the same worktree. +- Before cherry-picking an isolated commit, inspect `git show --stat` and ensure + it contains only project files. Two earlier agents accidentally committed + `.superpowers/sdd/task-*-report.md`; those scratch reports were removed by + `490c053` and `2bc090c`. Put future reports under `/tmp`. +- After review approval, cherry-pick into the canonical integration worktree, + run fresh controller-side focused checks, and update the scratch ledger. +- Preserve unrelated changes and never edit + `packages/backend/convex/_generated/**` or `packages/backend/convex/http.ts`. +- Commits must use a simple `git commit -m "message"` with no AI attribution. +- Use conventional commit messages and minimal comments. +- Run `bun typecheck`, not a production build, for routine validation. + +## Environment and validation limitations + +The local server, local database, Docker-backed worker, and Convex deployment +are unavailable. Continue implementation and static/unit checks as requested; +record live/manual checks for later. + +Root `bun install --frozen-lockfile` fails on the untouched baseline because +Bun 1.3.10 wants to rewrite the lockfile. The integration worktree currently +uses a root `node_modules` symlink to the original checkout. Do not commit any +dependency artifacts or lockfile rewrite merely to work around this. + +Convex codegen cannot run without `CONVEX_SELF_HOSTED_URL` plus admin key or +`CONVEX_DEPLOYMENT`. For backend unit tests/typecheck that do not require newly +generated API declarations, temporarily link the ignored generated snapshot: + +```bash +cd packages/backend +ln -s /home/gib/Documents/Code/Spoon/packages/backend/convex/_generated convex/_generated +bun run test:unit -- +bun run typecheck +rm convex/_generated +``` + +Never commit that symlink and do not claim fresh codegen succeeded. New API +typing may remain unavailable until deployment credentials return. + +For Next component tests in a worktree, temporarily make the Vitest workspace +package resolve inside that worktree: + +```bash +mkdir -p apps/next/node_modules/@spoon +ln -s ../../../../tools/vitest apps/next/node_modules/@spoon/vitest-config +cd apps/next +bun run test:component +cd ../.. +rm apps/next/node_modules/@spoon/vitest-config +rm -r apps/next/node_modules/.vite apps/next/node_modules/.vite-temp 2>/dev/null || true +rmdir apps/next/node_modules/@spoon apps/next/node_modules 2>/dev/null || true +``` + +## Known deferred/manual checks + +- Inspect a live `spoon-box-*` and confirm Docker `HostConfig.Init` is true. +- Verify real terminal resize, glyph rendering, and tmux reconnect in a browser. +- Verify Task 6 cancellation kills only the selected job's Codex process group + under real Docker and Podman. +- Run each phase's plan-specific live/manual checks when the local stack returns. +- Task 9 has one non-blocking review note: worker-auth tests assert + `ConvexError` type but not both exact error strings. Consider covering this + during final review. +- The realpath containment design has the documented validation-to-I/O TOCTOU + window; descriptor-relative elimination was outside the approved plan. + +## Final completion requirements + +After all 63 tasks: + +1. Run a broad whole-branch review against the design spec and all five plans. +2. Fix all Critical/Important findings in one coordinated pass and re-review. +3. When the environment is available, run `bun typecheck`, + `SKIP_E2E=1 bun run ci:check`, `bun test:e2e`, container smoke, and the + documented live runtime/manual checks. Until then, report them as deferred, + not passing. +4. Use the finishing-development-branch workflow; do not merge, push, or open a + PR unless the user explicitly requests it. +