docs: add implementation handoff for Claude
This commit is contained in:
Gabriel Brown
@@ -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/<pid>/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 -- <focused-test>
|
||||
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.
|
||||
|
||||
Reference in New Issue
Block a user