ADK path canonicalization + write-location transparency + artifact hygiene (v6.5.0)#75
Merged
Merged
Conversation
added 20 commits
June 3, 2026 14:00
…ifact hygiene (v6.5.0)
…, placeholder-aware gate, dedicated CI workflow, authoritative 12-hook list
…p scope-lock-claim (11 hooks), session-start/pre-compact anchors, behavioral degradation test
… 4 resolver cases
…ate to skills/ + minors - Critical: scope-lock-complete/abandon prune_jsonl compared against $ADK_ROOT but plan_abs uses $PWD -> stale lock never pruned in a worktree. Both now use $PWD (state files stay at $ADK_ROOT). Group D worktree regression test added (RED w/ bug, GREEN w/ fix). - Important: no-machine-paths.sh now scans skills/ + agents/ too (the skill rule claims enforcement); sanitized 3 pre-existing /Users/jon leaks to placeholders. - Minor: test header 12->11; lib shebang -> shellcheck shell=bash (sourced file).
Contributor
There was a problem hiding this comment.
Pull request overview
This PR addresses worktree-related ADK state fragmentation by introducing a shared canonical “state root” resolver (anchored to the git common dir), retrofitting state-writing hooks to use it, and adding CI enforcement to prevent operator home-directory paths from leaking into committed artifacts. It also adds a “Writes:” ledger convention for subagent transparency and bumps the kit version to v6.5.0.
Changes:
- Add
hooks/lib-autodev-paths.shand update 11 hooks to resolve ADK state via a canonical root shared across worktrees. - Add/extend regression tests and CI wiring for canonicalization behavior and artifact path hygiene.
- Update skills/prompts/docs to require a
Writes:ledger and to replace literal machine paths with placeholder forms.
Reviewed changes
Copilot reviewed 39 out of 39 changed files in this pull request and generated 8 comments.
Show a summary per file
| File | Description |
|---|---|
tests/no-machine-paths.sh |
New gate script to detect operator-home absolute paths in committed artifacts. |
tests/hook-contracts.sh |
Adjusts scope-lock-complete test invocation to run from tmp cwd (matches new canonical-root behavior). |
tests/adk-path-canonicalization.sh |
New regression test for resolver behavior, hook wiring, degradation behavior, and worktree-prune fix. |
skills/writing-plans/SKILL.md |
Adds repo-relative/placeholder path hygiene rule referencing the new test gate. |
skills/using-git-worktrees/SKILL.md |
Replaces literal /Users/<realname>/... example with placeholder segment. |
skills/systematic-debugging/root-cause-tracing.md |
Sanitizes example machine path to placeholder form. |
skills/systematic-debugging/CREATION-LOG.md |
Sanitizes example machine path to placeholder form. |
skills/subagent-driven-development/spec-reviewer-prompt.md |
Requires subagents to end with a Writes: ledger. |
skills/subagent-driven-development/SKILL.md |
Documents write-location transparency requirement (Writes: ledger). |
skills/subagent-driven-development/implementer-prompt.md |
Requires subagents to end with a Writes: ledger. |
skills/subagent-driven-development/code-quality-reviewer-prompt.md |
Requires subagents to end with a Writes: ledger. |
skills/recording-decisions/SKILL.md |
Adds repo-relative/placeholder path hygiene rule referencing the new test gate. |
skills/post-merge-retrospective/SKILL.md |
Updates retro instructions to read activation logs from canonical repo root; adds path hygiene rule. |
skills/brainstorming/SKILL.md |
Adds repo-relative/placeholder path hygiene rule referencing the new test gate. |
skills/adversarial-design-review/SKILL.md |
Adds repo-relative/placeholder path hygiene rule referencing the new test gate. |
hooks/subagent-scope-guard |
Resolves .claude/autodev-state access via canonical root. |
hooks/session-start |
Resolves .claude/autodev-state access via canonical root. |
hooks/scope-lock-complete |
Moves state file paths under canonical root; fixes prune comparison base for worktrees. |
hooks/scope-lock-abandon |
Moves state file paths under canonical root; fixes prune comparison base for worktrees. |
hooks/record-activity |
Writes activation log under canonical root. |
hooks/prompt-strict-interpretation |
Resolves .claude/autodev-state access via canonical root. |
hooks/pretool-pr-review-reminder |
Dedup marker moved to canonical root. |
hooks/pretool-demo-fidelity-guard |
State dir moved to canonical root. |
hooks/pre-tool-scope-guard |
Session-lock state dir moved to canonical root. |
hooks/pre-compact-snapshot |
Reminder marker + activation log paths moved to canonical root. |
hooks/lib-autodev-paths.sh |
New shared resolver (autodev_repo_root) for canonical state-root resolution. |
hooks/completion-claim-guard |
Reads phase-progress/state under canonical root. |
docs/testing.md |
Replaces real machine path with placeholder-based example. |
docs/plans/2026-06-03-adk-path-canonicalization.md.scope-lock |
New scope-lock hash artifact for the plan. |
docs/plans/2026-06-03-adk-path-canonicalization.md |
New plan artifact documenting the change and verification steps. |
docs/plans/2026-06-03-adk-path-canonicalization-plan-review.md |
New adversarial plan-phase review report artifact. |
docs/plans/2026-06-03-adk-path-canonicalization-design.md |
New design artifact describing canonicalization + hygiene + ledger conventions. |
docs/plans/2026-06-03-adk-path-canonicalization-design-review.md |
New adversarial design-phase review report artifact. |
agents/team-conventions.md |
Adds the Writes: ledger convention for subagents. |
.github/workflows/skill-content-check.yml |
Ensures hook changes trigger CI and runs the canonicalization test. |
.github/workflows/path-hygiene.yml |
New always-on workflow enforcing the no-machine-paths gate. |
.cursor-plugin/plugin.json |
Version bump to 6.5.0. |
.claude-plugin/plugin.json |
Version bump to 6.5.0. |
.claude-plugin/marketplace.json |
Version bump to 6.5.0. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
73
to
+76
| plan_dir=$(cd "$(dirname "$plan_abs")" && pwd) | ||
| repo_root=$(cd "${plan_dir}/../.." && pwd) | ||
| . "$(cd -- "$(dirname -- "${BASH_SOURCE[0]:-$0}")" && pwd)/lib-autodev-paths.sh" 2>/dev/null || true | ||
| declare -f autodev_repo_root >/dev/null 2>&1 || autodev_repo_root() { printf '%s\n' "${1:-$PWD}"; } | ||
| ADK_ROOT="$(autodev_repo_root "$PWD")" |
Comment on lines
75
to
+78
| plan_dir=$(cd "$(dirname "$plan_abs")" && pwd) | ||
| repo_root=$(cd "${plan_dir}/../.." && pwd) | ||
| . "$(cd -- "$(dirname -- "${BASH_SOURCE[0]:-$0}")" && pwd)/lib-autodev-paths.sh" 2>/dev/null || true | ||
| declare -f autodev_repo_root >/dev/null 2>&1 || autodev_repo_root() { printf '%s\n' "${1:-$PWD}"; } | ||
| ADK_ROOT="$(autodev_repo_root "$PWD")" |
Comment on lines
+4
to
+7
| set -uo pipefail | ||
| ROOT="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")/.." && pwd)" | ||
| LIB="$ROOT/hooks/lib-autodev-paths.sh" | ||
| failures=0 |
|
|
||
| **Goal:** Make all ADK state writes resolve to one canonical per-repo location (worktree-safe), have subagents report where they wrote, and forbid operator-home paths in committed artifacts — fixing the #70 worktree-fragmentation residual. | ||
|
|
||
| **Architecture:** One shared bash resolver (`hooks/lib-autodev-paths.sh`, git-common-dir-anchored with cwd fallback + lib-missing degradation) sourced by the 12 state-writing hooks; a subagent `Writes:` ledger convention; a placeholder-aware path-hygiene CI gate in its own always-run workflow. TDD via a real temp `git worktree` fixture proving the resolver. v6.5.0 version bump. |
|
|
||
| **PR Count:** 1 | ||
| **Tasks:** 10 | ||
| **Estimated Lines of Change:** ~420 (1 lib + 12 hook retrofits + 2 tests + 1 workflow + 6 skill/agent edits + version bump) |
Comment on lines
+49
to
+52
| #!/usr/bin/env bash | ||
| # tests/adk-path-canonicalization.sh — proves the canonical ADK state-path resolver | ||
| # and that all 12 state-writing hooks adopt it. (#70 residual; v6.5.0) | ||
| set -uo pipefail |
Comment on lines
+131
to
+134
| ```sh | ||
| #!/usr/bin/env bash | ||
| # lib-autodev-paths.sh — canonical ADK state-root resolver, sourced by state-writing hooks. | ||
| # autodev_repo_root <cwd> -> canonical repo root (shared across worktrees, survives worktree removal). |
Comment on lines
+7
to
+10
| set -uo pipefail | ||
| ROOT="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")/.." && pwd)" | ||
| pattern='(/Users/|/home/)[A-Za-z0-9][A-Za-z0-9._-]*' | ||
| hits=0 |
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
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.
Summary
Fixes the #70 worktree-fragmentation residual (surfaced in the v6.4.0 retro) and generalizes it into a consistent solution for three directory-confusion problems. 11 state-writing hooks now resolve ADK state through one shared resolver; subagents report a
Writes:ledger; committed artifacts are CI-gated against operator-home path leaks.C1 — canonical state location (worktree-safe)
New
hooks/lib-autodev-paths.shexportingautodev_repo_root— anchors.claude/autodev-state+.autodev/stateto the git-common-dir's parent (the one root all worktrees share, surviving worktree removal), withAUTODEV_STATE_ROOToverride, cwd fallback,pwd -Pnormalization, and adeclare -fguard so a missing/broken lib degrades to today's behavior — hooks never break (the #66 lesson). All 11 state writers retrofitted (scope-lock-claimexcluded — comment-only match). The retro now reads the canonical log, closing #70.C2 — subagent write-location transparency
Every subagent ends with a
Writes:ledger (repo-relative paths +OUT-OF-TREE:flag) so the orchestrator can verify and relocate state. Convention added toteam-conventions.md+ the 3 prompt templates + the SKILL. (This PR's own implementer dogfooded it.)C3 — no machine paths in committed artifacts
Placeholder-aware
tests/no-machine-paths.sh(matches a real/Users/<realname>/leak, ignores<placeholder>segments + ellipsis, honors apath-hygiene-allowsentinel) in a dedicated always-onpath-hygiene.ymlworkflow (nopaths:filter, so a docs-only leak can't bypass it). Scansdocs/,decisions/,skills/,agents/. Fixed 4 pre-existing leaks (docs/testing.md+ 3 inskills/). State logs stay exempt (.claude/gitignored). Plus a one-line repo-relative-paths rule in 5 artifact-writing skills.Design / Plan / Adversarial reports (dogfood of #69's committed-report convention)
docs/plans/2026-06-03-adk-path-canonicalization-design.md(review:-design-review.md, 2 cycles → PASS)docs/plans/2026-06-03-adk-path-canonicalization.md(review:-plan-review.md, 3 cycles → PASS)Scope Manifest
PR Count: 1 · Tasks: 10 · Status: Locked (sha256 600c67aa…)
Verification (all green, lead-verified from clean tree)
tests/adk-path-canonicalization.sh→ 0 failures. Resolver proven against a real temp git + linked worktree: main-checkout and worktree both resolve to the identical physical root; non-git → cwd fallback; override; lib-missing degradation writes to cwd fallback without crashing; Group D proves a worktreescope-lock-completeprunes the canonical session-lock (revert-restore confirmed it catches the bug).no-machine-paths.sh,hook-contracts.sh,hook-stdout-discipline.sh,skill-content-grep.sh,skill-cross-refs.sh,version-check.sh,plan-scope-check --verify-lock→ all exit 0.Adversarial code review
REQUEST CHANGES → all resolved: 1 Critical (worktree prune compared against
$ADK_ROOTnot$PWD→ stale locks; fixed + Group D regression test) + 1 Important (gate didn't scanskills/while the rule claimed enforcement; extended + leaks fixed) + 2 minors.Doc-reconciliation: clean (Step 1e dogfooded — docs match the built hooks;
no-machine-paths.shis the mechanical proof).Pipeline: brainstorming → design (adversarial ×2) → plan (adversarial ×3) → alignment → scope-lock → execute → adversarial code review. Copilot review welcome, non-blocking.
🤖 Generated with Claude Code