Add per-task state record (status + session links)#38
Merged
Conversation
Introduce a small JSON file colocated with the handoff at ~/.cdd/handoffs/<repo>/<branch>.state.json, written by the slash commands at their stage transitions and read by external consumers (cdd-dash). It captures a task's stage + finer status, the PR number once opened, and the append-only chain of Claude Code sessions that worked it (each session link is `claude --resume <id>`, derived from $CLAUDE_CODE_SESSION_ID). The record is advisory and reconstructible: a local cache describing work on this machine, explicitly not a cross-machine transfer mechanism (issue #22) and not an event history (snapshot + timestamps only). It is an additive sibling of the handoff and fits the frozen worktree-helper contract without enlarging it — the helper only deletes it. - Process doc: new §2.13 documenting the schema, stage/status vocabulary, session mechanism, and non-goals; pointers from §2.6/§2.8/§3.3. - Commands (repo + template copies, drift-checked parity): /cdd-next-step seeds the record and instructs the implementation session to write plan_approved / implementation_done; /cdd-merge-base, /cdd-pre-pr (checks_passed + pr_open), and /cdd-process-pr record their transitions. In-worktree writers derive the path at runtime (drift-free); next-step uses its existing hardcoded-slug path. - cdd-worktree.sh: cdd-worktree-done deletes the .state.json sibling alongside the handoff (only when the branch is deleted); the stale sweep in /cdd-next-step removes it too. - settings.json (both copies): allow Write to the handoff dir, rm of *.state.json, and hostname / date -u for stamping. cdd-dash consumption is a mechanical follow-up in that repo; no roadmap change (off-roadmap, intent-driven). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Pre-PR reconciliation: the state-record feature was off-roadmap intent-driven work with no existing checkbox. Record the landed item plus its named downstream follow-ups (consume the record in cdd-worktree-list/cdd-dash; multi-machine resume, issue #22). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
drabaioli
commented
Jun 29, 2026
Record the investigation outcome: a dual-mode cdd-state helper for atomic writes plus a gh-pr-create PostToolUse hook for the one outcome-bearing transition. Note that a fully guaranteed UserPromptSubmit/Expansion trigger fires at invocation only, so it cannot capture outcomes (checks_passed, PR number) the model produces mid-run. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Replace the prompt-driven JSON hand-editing with tools/cdd-state.sh, a
dual-mode self-installing helper (like cdd-worktree.sh): cdd-state seed
<branch> creates the record, cdd-state set <stage> [--pr NN] advances it.
Writes are atomic (temp-file + rename) and well-formed, so the
malformed-JSON / wrong-field failure mode of hand-editing is gone; the
model still decides when. Absent jq or an absent record, it no-ops.
Simplify the schema per review: squash stage+status into a single stage
enum, trim session entries to {id, stage}, and drop the url, machine,
created_at, updated_at, recorded_at fields (all speculative / no current
consumer). Every command's verbose state paragraph collapses to one
cdd-state line, which also removes the process-doc references from the
prompts. settings.json swaps the Write/hostname/date allows for
Bash(cdd-state*).
Addresses PR #38 review: #3494362739, #3494407885, #3494415079,
#3494288014, #3494420020, #3494418136, #3494308377, #3493923487,
#3494324754.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…n motivation Process doc §2.13 rewritten around the session resume-chain (find/resume the session that worked a branch) as the primary payoff; cdd-dash is one downstream consumer, not the justification. Documents the cdd-state helper, the single stage enum, and the slimmed schema. §2.8 gains a note on the companion helper; the frozen three-command worktree contract is unchanged. Roadmap: mark the helper done (Phase 13a), narrow the remaining hardening to the gh-pr-create PostToolUse hook, and scope the consume item to cdd-dash (cdd-worktree-list infers fine, doesn't need the record). Architecture/feature/BOOTSTRAP updated for the second self-installing helper and the settings allow change. Addresses PR #38 review: #3494396840, #3494425533, #3494430578, #3494436426. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The repo's own .claude/settings.json now mirrors the template: drop the unused Write/hostname/date allows and add Bash(cdd-state*), so this repo's CDD sessions can run the state helper without a prompt. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…UDE.md Merging main brought in scripts/prompt-seam-check.sh (#37), whose check-1 regex extracts /cdd-state from file paths like tools/cdd-state.sh — the same false positive /cdd-worktree is whitelisted for. Add /cdd-state to the whitelist, and list cdd-state.sh in CLAUDE.md's bash -n line and tools/ row. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
drabaioli
commented
Jun 30, 2026
Trim the completed state-record item to a summary plus a pointer to process doc §2.13 (which holds the full design/schema, so no info is lost), and tighten the PR-number-hook follow-up. Addresses PR #38 review: #3500597168. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Capture the deferred cleanup surfaced in PR #38 review: commands point at the large process doc ~14 times, loading it into context each run. Record as a tracked efficiency task rather than expanding this PR. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds a per-task state record — a
<branch>.state.jsonsibling of the handoff file — that records where a task sits in its lifecycle (stage/status) and which Claude Code sessions have worked it (an append-onlysessionschain withclaude --resumelinks). It is an additive, advisory, local-only sibling of the handoff: same per-repo directory, same<branch>basename, same branch-scoped/ephemeral lifecycle.The motivating consumer is an external dashboard (
cdd-dash); this PR only lands the producer side. Consuming the record (teachingcdd-worktree-list/cdd-dashto read it) and multi-machine resume (issue #22) are tracked as follow-ups.How
Process-first, then template (drift clean):
claude-driven-development.md: new §2.13 (schema, vocabulary, writer/consumer contract), plus updates to §2.6 (handoff has a state sibling), §2.8 (helper deletes it), §3.3 (implementation session writes it)./cdd-next-stepseeds the record; the implementation session updates it twice (plan-approved, implementation-done) via a standing handoff instruction;/cdd-merge-base,/cdd-pre-pr,/cdd-process-pradvance it at their stage transitions.tools/cdd-worktree.sh:cdd-worktree-donedeletes the state record alongside the handoff iff the branch was deleted.settings.json(repo + template): allowWriteto the handoff dir,rm *.state.json,hostname,date -u*.Verification
bash -n(scripts/tools/demo) ✓ · command-set drift ✓ clean · install smoke ✓ · end-to-end bootstrap smoke ✓ · demo seed-overlay smoke ✓settings.jsonsubstitutes correctly and picks up the new allows.Notes
cdd-worktree-doneships untested: that function is fully interactive (readprompts,git worktree remove,gh, branch deletion) and has no existing harness; the new logic is two lines mirroring the adjacent handoff deletion. Recorded as an "untested-with-reason" outcome; a non-interactive harness for it is a possible future task.