Restore process doc to workflow altitude; relocate tooling mechanics (#47)#50
Merged
Conversation
…47) The process doc had accumulated implementation detail that belongs in proper documentation: shim behaviour, rc-block self-repair, subshell/cwd rationale, the curl fetch-and-install one-liner, atomic-write and session-id mechanics, and retrofit git-isolation fallbacks. - New doc/architecture/shell-helpers.md is the narrative home for the cdd-worktree / cdd-state install model, PATH shims and the cwd constraint, runtime derivation, atomic state writes, and resume discovery; the scripts' own comments stay the finest-grained reference. - doc/architecture/bootstrap-and-retrofit.md absorbs the retrofit isolation fallback ladder (unborn HEAD, non-repo, dirty-tree warning). - The process doc keeps the workflow-level contracts and invariants, with one-line pointers to the relocated mechanics (sections 2.8, 2.10, 2.13, 6, 7). - A "Document altitude" guideline at the top of the process doc, plus a CLAUDE.md critical constraint, establish the rule so the drift doesn't recur: if a passage would change when a script is refactored without the workflow changing, it belongs next to the code. Process-doc-only on the template axis by design: the process doc and architecture docs are repo-local, so no template counterpart changes. Closes #47 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018hzCeczgEKmVSZkbL5DcHz
Full restructuring pass following the targeted trim: the process doc now
carries only the workflow itself — philosophy, artifact definitions and
rules, lifecycle, checkpoints, edit rules — at 364 lines (from 553),
with capability detail and mechanics relocated to their proper homes:
- doc/features/template.md gains the shared scope-triage heuristic
("Deliverable or project?") and the retrofit cost analysis
(first-time vs upgrade, don't-disrupt-existing-docs shapes).
- doc/architecture/shell-helpers.md gains the state-record schema and
the stage-to-writer table.
- doc/architecture/overview.md gains the meta-project rationale from
section 7.1 (dogfooding, the process doc's own location).
- Process doc sections 2, 3, 6, 7 compressed to definitions, rules, and
pointers; section numbering and load-bearing headings preserved so
inbound references (commands, shell helpers, whitelists, CLAUDE.md)
stay valid. The handoff schema stays in section 2.6, which
command-drift-check.sh asserts against cdd-next-step.md.
- cdd-bootstrap.md and cdd-quick-create.md now point at the heuristic's
new home in the feature doc.
Repo-local docs and CDD-repo-only commands on the template axis; no
template counterpart changes needed.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018hzCeczgEKmVSZkbL5DcHz
drabaioli
added a commit
that referenced
this pull request
Jul 20, 2026
#51) (#52) * Record the handoff session and per-session dir in seeded state records cdd-state seed previously wrote sessions: [], so the /cdd-next-step handoff session (which seeds the record on the main worktree) was never recorded and could not be resumed; only the implementation session's first `set` landed an id. Seed now records the current session as the first {id, stage: scoped, dir} entry when CLAUDE_CODE_SESSION_ID is set (empty list otherwise — older Claude Code, don't guess), and every session entry in both seed and set carries a `dir` = the worktree root (git rev-parse --show-toplevel), the natural cd target for `claude --resume`. `dir` is additive and optional: no CDD_STATE_SCHEMA_VERSION bump, so old and new records interoperate (readers ignore unknown fields; the reader half is cdd-dash PR #10, which falls back to the row's worktree path when dir is absent). Closes the writer half of issue #51. Docs updated to match: the helper header block, process doc §2.13 (schema example, append-only paragraph, scoped table row), and a checked Phase 13 roadmap item. install-smoke-assert.sh gains a jq-guarded assertion that seed records the handoff session with its dir, and omits the entry when no session id is set. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * adopt: port #51 dir/handoff-session detail into relocated shell-helpers.md Merge with origin/main (#50) relocated the state-record schema and stage-to-writer table from process-doc §2.13 into doc/architecture/shell-helpers.md. The §2.13 conflict was resolved by taking #50's condensed version; this ports the issue #51 semantics into their new home: the `dir` field on session entries, the schema note that `dir` is additive/optional, that seeding records the handoff session as the first entry, and the updated `scoped` writer row. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * reconcile: point state-record roadmap items at shell-helpers.md schema #50 relocated the state-record schema out of process doc §2.13 into doc/architecture/shell-helpers.md. Update the two completed roadmap items (#51 writer half, and the earlier per-task-record item) so their file trails point at where the schema actually lives. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- 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
2 participants
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.
The process doc had accumulated implementation detail that belongs in
proper documentation: shim behaviour, rc-block self-repair, subshell/cwd
rationale, the curl fetch-and-install one-liner, atomic-write and
session-id mechanics, and retrofit git-isolation fallbacks.
cdd-worktree / cdd-state install model, PATH shims and the cwd
constraint, runtime derivation, atomic state writes, and resume
discovery; the scripts' own comments stay the finest-grained reference.
isolation fallback ladder (unborn HEAD, non-repo, dirty-tree warning).
with one-line pointers to the relocated mechanics (sections 2.8, 2.10,
2.13, 6, 7).
CLAUDE.md critical constraint, establish the rule so the drift doesn't
recur: if a passage would change when a script is refactored without
the workflow changing, it belongs next to the code.
Process-doc-only on the template axis by design: the process doc and
architecture docs are repo-local, so no template counterpart changes.
Closes #47
Co-Authored-By: Claude Fable 5 noreply@anthropic.com
Claude-Session: https://claude.ai/code/session_018hzCeczgEKmVSZkbL5DcHz