fix(skills): diff installed skills against bundled template by default

Default `brigade skills diff` to the Brigade package template so stale
registry copies cannot mask drift from newer bundled skills. Add
`--against registry` for the previous registry baseline. Fixes #484.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: solomonneas

docs/technical-guide.md

@@ -889,7 +889,7 @@ Shared skill registry commands:
 - `brigade skills sync --workspace . --target all --trust workspace` scans the reviewed registry once and reports each selected skill and harness as current, missing, changed, blocked, or excluded. It is a dry run unless `--write` is present. Writes use explicit registry identities and the existing per-target receipt and rollback path, so completed targets survive a later target failure.
 - `brigade skills compatibility security-review` reports supported, installed, planned, and blocked harness targets for a skill, plus independent source, renderer, and local-copy drift, install history counts, trust score, and changelog status.
 - `brigade skills history security-review --harness codex` lists local install receipts for one skill and harness from `.brigade/skills/installs/history.jsonl`.
-- `brigade skills diff security-review --harness codex` compares the installed harness file against the current rendered resolved source. Bundled skills compare with the current Brigade package and report source, renderer, and local-edit drift separately. Receipts from older schemas report unknown provenance instead of guessing.
+- `brigade skills diff security-review --harness codex` compares the installed harness file against the bundled Brigade package template by default, even when a same-named registry entry exists. Pass `--against registry` to diff against the local `.brigade/skills/registry/` copy instead. Bundled skills report source, renderer, and local-edit drift separately. Receipts from older schemas report unknown provenance instead of guessing.
 - `brigade skills fleet status` reports installed skill copies across harnesses in stable order and prints one forced reinstall command for each supported stale or missing copy. Copies whose current metadata no longer supports their harness are listed separately as unsupported and get an uninstall command. Unknown legacy copies are listed without an automatic repair command.
 - `brigade skills rollback security-review --target claude` restores the latest rollback snapshot captured before a forced reinstall.
 - `brigade skills inbox add ./some-skill`, `list`, `show`, `diff`, `accept`, and `reject` keep agent-proposed skills in review before they enter the registry.

src/brigade/cli/skills.py

@@ -67,11 +67,18 @@ def register(sub: argparse._SubParsersAction) -> None:
     p_skills_history.add_argument("--limit", type=int, default=20, help="Maximum history rows to show.")
     p_skills_history.add_argument("--json", action="store_true", help="Print machine-readable JSON.")
     p_skills_diff = skills_sub.add_parser(
-        "diff", help="Diff an installed skill against the current rendered registry version."
+        "diff",
+        help="Diff an installed skill against the bundled Brigade template (default) or the local registry.",
     )
     p_skills_diff.add_argument("skill", help="Skill id, path, or directory.")
     p_skills_diff.add_argument("--target", "-t", type=Path, default=Path("."), help="Workspace registry to inspect.")
     p_skills_diff.add_argument("--harness", required=True, help="Harness target to compare.")
+    p_skills_diff.add_argument(
+        "--against",
+        choices=["bundled", "registry"],
+        default="bundled",
+        help="Comparison baseline: bundled package template (default) or local registry entry.",
+    )
     p_skills_diff.add_argument("--json", action="store_true", help="Print machine-readable JSON.")
     p_skills_fleet = skills_sub.add_parser("fleet", help="Inspect installed skill copies across harnesses.")
     skills_fleet_sub = p_skills_fleet.add_subparsers(dest="skills_fleet_command", metavar="<skills-fleet-command>")
@@ -251,7 +258,13 @@ def dispatch(args) -> int:
             json_output=args.json,
         )
     if args.skills_command == "diff":
-        return skills_cmd.diff(target=args.target, skill=args.skill, harness=args.harness, json_output=args.json)
+        return skills_cmd.diff(
+            target=args.target,
+            skill=args.skill,
+            harness=args.harness,
+            against=args.against,
+            json_output=args.json,
+        )
     if args.skills_command == "fleet":
         if args.skills_fleet_command == "status":
             return skills_cmd.fleet_status(target=args.target, json_output=args.json)

src/brigade/skills_cmd.py

@@ -463,6 +463,37 @@ def _bundled_skill_path(skill_id: str) -> Path:
     return template_root() / "skills" / _slug(skill_id)
 
 
+def _bundled_skill_exists(skill_id: str) -> bool:
+    return _skill_md_path(_bundled_skill_path(skill_id)).is_file()
+
+
+def _resolve_diff_baseline(target: Path, skill_or_path: str, *, against: str = "bundled") -> str:
+    requested = str(skill_or_path)
+    candidate = Path(requested).expanduser()
+    if candidate.exists():
+        return requested
+    if requested.startswith("registry:"):
+        skill_id = _slug(requested.removeprefix("registry:"))
+    elif requested.startswith("bundled:"):
+        skill_id = _slug(requested.removeprefix("bundled:"))
+    else:
+        skill_id = _slug(requested)
+    registry_dir = _skill_path(target, skill_id)
+    registry_exists = _skill_md_path(registry_dir).is_file()
+    bundled_exists = _bundled_skill_exists(skill_id)
+    if against == "registry":
+        if registry_exists:
+            return f"registry:{skill_id}"
+        if bundled_exists:
+            return f"bundled:{skill_id}"
+        return requested
+    if bundled_exists:
+        return f"bundled:{skill_id}"
+    if registry_exists:
+        return f"registry:{skill_id}"
+    return requested
+
+
 def _source_identity(*, skill_dir: Path, skill_id: str, kind: str, reviewed: bool) -> dict[str, Any]:
     if kind == "brigade-bundle":
         identity = f"{BUNDLED_SOURCE_PREFIX}{skill_id}"
@@ -1540,9 +1571,10 @@ def history(
     return 0
 
 
-def diff(*, target: Path, skill: str, harness: str, json_output: bool = False) -> int:
+def diff(*, target: Path, skill: str, harness: str, against: str = "bundled", json_output: bool = False) -> int:
     target = target.expanduser().resolve()
-    lint_payload = _lint_payload(target, skill)
+    baseline_skill = _resolve_diff_baseline(target, skill, against=against)
+    lint_payload = _lint_payload(target, baseline_skill)
     if not lint_payload["valid"]:
         if json_output:
             print(
@@ -1588,6 +1620,8 @@ def diff(*, target: Path, skill: str, harness: str, json_output: bool = False) -
         "target": str(target),
         "skill_id": skill_id,
         "harness": harness,
+        "against": against,
+        "baseline_skill": baseline_skill,
         "installed": installed_skill.is_file(),
         "installed_path": str(installed_skill),
         "changed": bool(diff_lines),

tests/test_skills_cmd.py

@@ -927,6 +927,76 @@ def test_bundled_install_and_diff_share_canonical_source(tmp_path, capsys):
     }
 
 
+def test_skills_diff_defaults_to_bundled_template_over_stale_registry(tmp_path, capsys):
+    stale = _write_skill(tmp_path / ".brigade" / "skills" / "registry", name="brigade-work")
+    (stale / "SKILL.md").write_text("# stale registry copy\n")
+
+    assert (
+        skills_cmd.install(workspace=tmp_path, skill="registry:brigade-work", harness="claude", json_output=True) == 0
+    )
+    capsys.readouterr()
+
+    assert skills_cmd.diff(target=tmp_path, skill="brigade-work", harness="claude", json_output=True) == 0
+    diff = json.loads(capsys.readouterr().out)
+    assert diff["against"] == "bundled"
+    assert diff["baseline_skill"] == "bundled:brigade-work"
+    assert diff["source"]["kind"] == "brigade-bundle"
+    assert diff["changed"] is True
+    assert diff["drift"]["content_changed"] is True
+
+
+def test_skills_diff_registry_selector_still_uses_bundled_by_default(tmp_path, capsys):
+    stale = _write_skill(tmp_path / ".brigade" / "skills" / "registry", name="brigade-work")
+    (stale / "SKILL.md").write_text("# stale registry copy\n")
+
+    assert (
+        skills_cmd.install(workspace=tmp_path, skill="registry:brigade-work", harness="claude", json_output=True) == 0
+    )
+    capsys.readouterr()
+
+    assert skills_cmd.diff(target=tmp_path, skill="registry:brigade-work", harness="claude", json_output=True) == 0
+    diff = json.loads(capsys.readouterr().out)
+    assert diff["baseline_skill"] == "bundled:brigade-work"
+    assert diff["changed"] is True
+
+
+def test_skills_diff_against_registry_compares_installed_to_registry(tmp_path, capsys):
+    stale = _write_skill(tmp_path / ".brigade" / "skills" / "registry", name="brigade-work")
+    (stale / "SKILL.md").write_text("# stale registry copy\n")
+
+    assert (
+        skills_cmd.install(workspace=tmp_path, skill="registry:brigade-work", harness="claude", json_output=True) == 0
+    )
+    capsys.readouterr()
+
+    assert (
+        skills_cmd.diff(
+            target=tmp_path,
+            skill="brigade-work",
+            harness="claude",
+            against="registry",
+            json_output=True,
+        )
+        == 0
+    )
+    diff = json.loads(capsys.readouterr().out)
+    assert diff["against"] == "registry"
+    assert diff["baseline_skill"] == "registry:brigade-work"
+    assert diff["source"]["kind"] == "registry"
+    assert diff["changed"] is False
+
+
+def test_skills_diff_matches_bundled_template_reports_clean(tmp_path, capsys):
+    assert skills_cmd.install(workspace=tmp_path, skill="brigade-work", harness="cursor", json_output=True) == 0
+    capsys.readouterr()
+
+    assert skills_cmd.diff(target=tmp_path, skill="brigade-work", harness="cursor", json_output=True) == 0
+    diff = json.loads(capsys.readouterr().out)
+    assert diff["baseline_skill"] == "bundled:brigade-work"
+    assert diff["changed"] is False
+    assert diff["drift"]["content_changed"] is False
+
+
 def test_explicit_registry_source_does_not_inherit_bundled_review(tmp_path, capsys):
     source = _write_skill(tmp_path / "source", name="brigade-work")
     assert skills_cmd.import_skill(target=tmp_path, source=source, json_output=True) == 0