Skip to content

feat: add machine protocol v1#33

Merged
zywkloo merged 5 commits into
mainfrom
feat/machine-protocol-v1
Jun 14, 2026
Merged

feat: add machine protocol v1#33
zywkloo merged 5 commits into
mainfrom
feat/machine-protocol-v1

Conversation

@zywkloo

@zywkloo zywkloo commented Jun 13, 2026

Copy link
Copy Markdown
Owner

Summary

  • add machine protocol v1 docs plus wtcraft --version and capabilities --json
  • add explicit --repo targeting and stable check --json / verify --json output
  • fix init --local in linked worktrees and make new base-branch resolution tolerant of origin/HEAD, main, master, develop, and the current branch
  • select Rust for the future extracted core while retaining Bash as the reference implementation until contract parity
  • define canonical Session Model v1 and Task State Machine v1 contracts, with a protocol index and extraction-readiness checklist
  • specify shared Bash/Rust contract fixtures, structural comparison and normalization rules, required coverage, and the default-switch compatibility gate

Testing

  • bash tests/run_all.sh
  • git diff --check
  • ./scripts/wtcraft verify feat/machine-protocol-v1

@zywkloo zywkloo left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Overall, this is an exceptionally rigorous update. The bash scripting for JSON construction, NUL-delimited parsing, and worktree discovery is extremely solid. The fallback logic for detached worktrees and the usage of git_info_exclude_path perfectly handle edge cases with linked worktrees.

I've reviewed the diff closely and have a few skeptical observations and suggestions, though most are non-blocking or just things to be aware of:

1. scripts/wtcraft (line 427)

The json_escape function:
This is a very clever implementation! Stripping control characters using tr -d '\000-\007\013\016-\037' while leaving the JSON-valid ones (like \b, \t, \n) to be explicitly escaped later is a great way to handle binary garbage in bash strings. Also, correctly doing the backslash replacement s="${s//\\/\\\\}" before adding your own backslashes for newline/tabs ensures they don't get double-escaped. Brilliant.

2. scripts/wtcraft (line 1082)

Git Diff quoting in cmd_check:
When git diff --name-only outputs files with spaces or non-ASCII characters, Git wraps them in double quotes and escapes them by default (unless core.quotePath is false). Since you are iterating line-by-line using read -r line (without -z), a file like "my file.txt" will be stored in changed_files with literal quotes. When this hits json_escape(), it gets double-escaped in the JSON (e.g., "\"my file.txt\"").
Suggestion: Consider using git diff -z --name-only and read -r -d '' for robust path handling in the future. (This is an existing flaw, not introduced by this PR, but worth noting for the machine protocol).

3. scripts/wtcraft (line 315)

Fixing info/exclude path resolution:
Changing ${repo_root}/.git/info/exclude to git_info_exclude_path is a great catch. Linked worktrees have .git as a plain text file, not a directory, so mkdir -p .git/info would fail in wtcraft init --local inside a linked worktree. Using --git-path correctly resolves to the common git dir.

4. scripts/wtcraft (line 915)

Stderr redirection in verify --json:
Redirecting child stdout to stderr (cd "$wt_path" && bash -lc "$cmd") >&2 when running in --json mode is very smart. It ensures the JSON payload on stdout isn't corrupted by rogue echos from the verification scripts.

5. scripts/wtcraft (line 384)

list_worktrees and detached HEADs:
Using awk with %c and 0 to produce NUL bytes is fantastic. One small note: if a worktree is checked out to a detached commit, git worktree list --porcelain does NOT output a branch line. Your awk script correctly falls through and assigns an empty string "" to the branch, which then smoothly fails the exact branch match in resolve_worktree_path and falls back to basename matching. This works perfectly.

No blockers. The architecture decisions in the PR description (selecting Rust for the future core but keeping Bash updated for parity) makes total sense. Great work.

@zywkloo zywkloo merged commit 214b424 into main Jun 14, 2026
1 check passed
zywkloo added a commit that referenced this pull request Jun 14, 2026
- Remove hardcoded VERSION; use read_cli_version() from PR #33
- Add --yes flag to migrate for non-interactive usage
- Detect non-interactive stdin and skip prompt gracefully
- Add dedicated usage_doctor and usage_migrate help text
- Add E2E tests for version, doctor, migrate --yes, and help

Co-Authored-By: Claude Opus 4.6 <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants