plugin-sync-explain

name	plugin-sync-explain
description	Read-only diagnostic for Lisa plugin source/generated drift. Compares plugins/src against generated plugins/lisa* status, reports source-not-built, generated-only, and marketplace registration drift, and preserves the working tree.
allowed-tools	["Bash","Read"]

Plugin Sync Explain: $ARGUMENTS

/lisa:plugin-sync-explain explains why the plugin sync gate would need attention without mutating the working tree.

Scope

Inspect the current Lisa repository, or an optional path passed as $ARGUMENTS, using scripts/plugin-sync-explain.mjs.

The diagnostic is read-only:

• Do not run bun run build:plugins.
• Do not run bun run check:plugins.
• Do not edit source files, generated plugin artifacts, or .claude-plugin/marketplace.json.
• Do not stash, commit, reset, or clean local changes.

What to Report

Report a concise terminal-first summary with stable classifications:

• SOURCE_NOT_BUILT: files under plugins/src/** changed without their generated plugins/lisa* counterpart.
• GENERATED_ONLY: files under plugins/lisa* changed without their plugins/src/** source counterpart.
• MARKETPLACE_REGISTRATION_DRIFT: a built plugin directory is missing from .claude-plugin/marketplace.json, or a marketplace source points at a missing built directory.
• OUT_OF_SYNC: source and generated counterparts both changed and need human review.
• IN_SYNC: no plugin source/generated or marketplace registration drift was detected.

For every finding, include the evidence path and the smallest source-first next action. Prefer bun run build:plugins only after source edits are in the right place, and preserve bun run check:plugins as the final reproducibility gate.

Process

1. Resolve the repo path from $ARGUMENTS or the current directory.
2. Capture git status --porcelain before the diagnostic.
3. Run:

   node plugins/lisa/scripts/plugin-sync-explain.mjs "$REPO_PATH"
   

   If running from the source tree before generated artifacts are rebuilt, use:

   node plugins/src/base/scripts/plugin-sync-explain.mjs "$REPO_PATH"
   

4. Capture git status --porcelain after the diagnostic and confirm it is unchanged.
5. Surface the script output plus the read-only confirmation.

Rules

• Keep this surface aligned with scripts/check-plugins-sync.sh; it explains the gate but does not replace it.
• Treat plugins/src/** as the source of truth and plugins/lisa* as generated artifacts.
• If the diagnostic cannot inspect git status or marketplace JSON, report the error plainly and do not guess.