Worktree-safe verify-local stamps; SPEC-0009 EINT v1/v2 layer clarification

[flyingrobots]

What

Two small, self-contained fixes from the Graft integration lane:

1. scripts/verify-local.sh: worktree-safe stamp storage. The stamp dir
   was hardcoded to .git/verify-local; in a linked worktree .git is a
   file, so mkdir failed and pre-commit aborted (mkdir: .git: Not a directory). Now resolves the real gitdir via git rev-parse --git-dir
   (with a .git fallback outside git contexts). Side benefit: stamps are
   per-worktree, so verification state in one worktree can't mask another's.

2. SPEC-0009: name the layer EINT v1 binds to. The spec documents the
   EINT v1 layout without saying it is the ABI v3 application-dispatch intake
   (OpticIntentPayload::EintV1 → KernelPort::dispatch_intent
   [crates/echo-wasm-abi/src/kernel_port.rs#2687@2048da5c]), and never
   mentions that a richer EINT v2 envelope exists at the session-protocol
   layer [crates/echo-session-proto/src/eint_v2.rs#3@2048da5c]. An external
   consumer reading the spec alone (ask me how I know) can't tell which
   envelope to implement. Added a source-cited note distinguishing the two.

How found

Building Graft's fake Echo-shaped TypeScript witness
(flyingrobots/graft, cycle/CORE_graft-fake-echo-shaped-typescript-witness):
the worktree hook crash hit on first commit in the lane/graft-integration
worktree, and the EINT ambiguity surfaced while validating the spec against
live source.

Review trail

• Self-review: citation lines verified against source at 2048da5c; the
  rev-parse substitution runs after the script's cd "$REPO_ROOT";
  set -euo pipefail-safe via || echo .git fallback.
• Hooks: the fixed pre-commit/pre-push verified the commit that ships them
  (markdownlint, prettier, bash -n) from inside a linked worktree.
• CodeRabbit: over to you.

Testing

• git commit + git push from a linked worktree (previously failed at
  pre-commit; now passes).
• bash -n scripts/verify-local.sh clean.
• Markdown lint clean on the spec change.

Summary by CodeRabbit

• Bug Fixes

  • Fixed verification/stamp handling for repositories using linked worktrees so local checks work when git metadata is stored as a file pointer.

• Documentation

  • Clarified ABI v3 "Intent Intake" byte layout and explicitly distinguished the ABI v3 application-dispatch format from the richer EINT v2 session-level envelope.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: c60a595b-47ca-4aee-8954-d9ac5bccba62

📥 Commits

Reviewing files that changed from the base of the PR and between d72e04a and 1465cfe.

📒 Files selected for processing (1)

• CHANGELOG.md

---

📝 Walkthrough

Walkthrough

This PR updates the verify-local script to resolve the real git directory for per-worktree stamp storage, and adds a SPEC-0009 clarification that ABI v3 application-dispatch consumes EINT v1 (OpticIntentPayload::EintV1) while EINT v2 is a separate session-level envelope; both changes are noted in CHANGELOG.md.

Changes

Git Worktree Support and ABI Documentation

Layer / File(s)	Summary
Git worktree stamp directory resolution scripts/verify-local.sh	Script resolves the actual git directory via git rev-parse --git-dir for the default STAMP_DIR, replacing the hardcoded .git/verify-local path that fails in linked worktrees.
ABI v3 intent intake specification and changelog docs/spec/SPEC-0009-wasm-abi-v3.md, CHANGELOG.md	Spec documents the EINT v1 ABI v3 intake byte layout routed through OpticIntentPayload::EintV1 → KernelPort::dispatch_intent, explicitly excluding the EINT v2 session-protocol envelope. Changelog records both the spec clarification and the worktree fix.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Poem

Worktrees point where .git once lay,
A script asks git and finds the true way.
EINT v1 lines the dispatch gate,
V2 sits apart, a different state.
Stamps settle neatly — clarity day.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes both main changes: worktree-safe stamp storage and EINT v1/v2 layer clarification. It's specific and covers the two self-contained fixes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch lane/graft-integration

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[flyingrobots]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.