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