verify-bundle-sync

Verify Bundle Sync

This skill exists solely to work around an upstream Claude Code symlink bug (anthropics/claude-code#53948) that requires plugins/dev-workflow-bundle/skills/<name>/ to be a real directory copy of skills/<name>/skills/<name>/ rather than a symlink. It is a project-local skill (lives under .claude/skills/verify-bundle-sync/, not registered in .claude-plugin/marketplace.json). When the bug is fixed and the bundle layout returns to symlinks, delete this skill directory, the .claude/dev-workflow.md test_commands entry, the dev-workflow-triage (d4) sub-step, and the .claude/rules/project.rules.md bullet that document this workaround.

The skill compares each bundle member's canonical directory against its bundle copy and reports drift. It is detect-only — it never modifies any files.

Process

Accepts an optional --base-commit <sha> argument (ignored — the scope is structural, not changeset-dependent). Running with no arguments behaves identically.

Run the following directly in the main thread (no subagent dispatch is needed — the check is lightweight: one jq invocation plus one diff -rq per bundle member).

Load the bundle membership list from .claude-plugin/marketplace.json:

bundle_skills=$(jq -r '(.plugins[] | select(.name == "dev-workflow-bundle") | .skills[]) // empty' .claude-plugin/marketplace.json 2>/dev/null)
# If $bundle_skills is empty after this guard, halt and emit the Return contract response
# (Layer 1 prose `Status: EXECUTION_ERROR` + Layer 2 fenced JSON with `status: "error"`,
# `reason: "marketplace.json missing, malformed, or dev-workflow-bundle plugin entry absent"`)
# immediately — see § Return contract.

The // empty is the array-enumeration null-fallback idiom: when the entry / array is absent, it yields a zero-length stream (no literal null\n leaking to stdout). This is a different concern from the canonical scalar // "unknown" pattern documented in .claude/rules/project.rules.local.md § jq の null String fallback, which targets scalar values. The post-pipeline [ -z "$output" ] guard catches array absence, jq non-zero exit, and file-not-found uniformly.

For each bundle member entry ./skills/<name>:
- Resolve canonical=skills/<name>/skills/<name>/
- Resolve bundle_copy=plugins/dev-workflow-bundle/skills/<name>/
- Verify both directories exist with test -d "$canonical" && test -d "$bundle_copy". If either is missing, exit immediately with EXECUTION_ERROR and report which path was missing.
- Run diff -rq "$canonical" "$bundle_copy". Capture stdout. If exit code is non-zero AND stdout is empty, treat as EXECUTION_ERROR (tool failure). If stdout is non-empty, treat every output line as a drift entry — each line is one of:
  - Files <canonical-path> and <bundle-copy-path> differ → type: "differ"
  - Only in <canonical-dir>: <file> → type: "only_in_canonical"
  - Only in <bundle-copy-dir>: <file> → type: "only_in_copy"
Aggregate the result:
- All entries drift-free → SUCCESS (e.g. 5 bundle skills verified, 0 drift)
- Any entry has drift → TEST_FAILED. Include the per-entry drift list and a remediation hint of the form cp -R skills/<name>/skills/<name>/. plugins/dev-workflow-bundle/skills/<name>/ for each affected member
- jq failed / diff missing / marketplace.json unreadable / per-entry path missing → EXECUTION_ERROR

EXECUTION_ERROR is deterministic within a run: marketplace.json absence, missing tooling (jq / diff), and missing path entries do not become resolved during the same run, so retrying the same invocation will not change the outcome. Callers that retry on EXECUTION_ERROR (such as dev-workflow Step 7's retry handler) will simply burn through their retry budget producing the same error each time — that wastes a few extra invocations but is harmless.

Return contract

The skill emits its result in two layers in a single response so that both prose-reading callers (such as dev-workflow Step 7) and JSON-parsing callers (such as dev-workflow-triage (d4)) can extract the verdict mechanically.

Layer 1 — Prose summary (first, at the top of the response):

Status: SUCCESS | TEST_FAILED | EXECUTION_ERROR

<one-paragraph human-readable summary>
<if TEST_FAILED: per-entry drift list with remediation hint lines>
<if EXECUTION_ERROR: reason and which step failed>

Layer 2 — Fenced JSON verdict (last, at the end of the response):

```json
{
  "status": "ok" | "drift" | "error",
  "checked_count": <int>,
  "drift_files": [{"skill": "<name>", "path": "<relative-path>", "type": "differ|only_in_canonical|only_in_copy"}],
  "reason": "<optional, required when status=error>"
}
```

Mapping between the prose status token and the JSON status field:

Prose `Status:`	JSON `status`
`SUCCESS`	`ok`
`TEST_FAILED`	`drift`
`EXECUTION_ERROR`	`error`

checked_count: number of bundle member entries actually inspected (5 at the time of writing — ask-peer, dev-workflow, extract-rules, rules-review, tidy). If the list could not be loaded (EXECUTION_ERROR from Step 1), set this to 0.
drift_files[]: drift / one-sided-presence entries, populated only for status: "drift". Empty array for ok and error. The path value preserves the raw line as it appeared in diff -rq output so that downstream rendering does not need to re-derive it.
reason: required on status: "error". Short, ≤ 80 characters. Examples: marketplace.json missing, dev-workflow-bundle plugin entry absent, jq not in PATH, canonical missing: skills/ask-peer/skills/ask-peer.

About this skill

Process

Return contract