fix(skills): replace divergent global Backscroll copies with product-owned symlinks

[pablontiv]

Description

The Backscroll product repository is the canonical owner of its backscroll skill, but global installations are regular directories with mixed content rather than product-owned symlinks.

Observed inventory:

Path	Type	Tree SHA-256
/Users/Shared/harness/backscroll/.claude/skills/backscroll	canonical directory	4361dc36a82ce812cf5d60409a9acdcc251439c239c6a0c60feea788a60e2dbc
~/.claude/skills/backscroll	regular directory, currently equal	4361dc36a82ce812cf5d60409a9acdcc251439c239c6a0c60feea788a60e2dbc
~/.agents/skills/backscroll	divergent regular directory	893d5755d17fbd42d1d66a87e5088d5bb83144841371ad5d299d040c366de60e
~/.config/opencode/skills/backscroll	divergent regular directory	c64838de2133cfb34ad788ef8cbe0071ad8fe792218434ea232763b5cfa2fe1b

None of these installed paths was reported as chezmoi-managed during the inventory.

Steps to reproduce

1. Compare each installed tree against .claude/skills/backscroll with a recursive file/content diff.
2. Inspect each path with lstat/readlink.
3. Observe that the Claude copy is byte-equivalent but still copied, while Agents/OpenCode copies diverge and none is a symlink.

Expected behavior

The Backscroll repository owns one canonical skill tree. Supported global runtimes resolve to that source through explicit, verifiable distribution links or another product-owned mechanism with equivalent single-source semantics.

Actual behavior

Three independent global directories can drift. Updating the product source does not update Agents/OpenCode, and even the currently equal Claude copy has no structural link to its owner.

Acceptance criteria

• Inventory exact installed preimages and canonical source commit/digest before mutation.
• Define supported destinations and eliminate unsupported duplicates explicitly.
• Back up every non-link destination before replacement.
• Require digest-bound approval before destructive replacement.
• Replace supported copies with product-owned symlinks that resolve strictly to the canonical skill tree on the product's stable checkout, never a temporary worktree.
• Verify discovery in each supported runtime and exact lexical/resolved paths.
• Provide rollback/restore evidence and an append-only receipt.
• Test filesystem behavior in temporary homes; never mutate the real home from tests.
• Document installation, update, verification, uninstall, and restoration ownership.

Environment

• Observed on macOS.
• Backscroll repository: https://github.com/pablontiv/backscroll

Scope boundary

Do not vendor Backscroll into pablontiv/skills; this product repository remains the canonical owner.

[pablontiv]

A new real usage incident confirms the impact of the divergent global skill copy.

The active ~/.agents/skills/backscroll/SKILL.md instructed the caller to use:

backscroll search "QUERY" --project <cwd-or-inferred> ...

Following that recipe with a filesystem path produced an empty result set because --project expects a semantic project ID and effectiveProject returns an explicitly supplied value unchanged. The canonical repository skill already contains the corrected guidance: rely on cwd inference first, and use --project <project-id> only when an explicit ID is needed.

This added an unnecessary fallback to --all-projects and several query refinements during a terminology-recall task even though the target response was already indexed under the current project. It provides a concrete acceptance scenario for this issue: after installation/update, every supported runtime must resolve the canonical skill version, and the Agents copy must no longer retain the stale path-shaped --project example.

[pablontiv]

[backscroll-team/investigador] 2026-09-06 UTC
[backscroll-team] Estado: needs-info

Reviewed main SHA: 1e698e58504bbb7ec83f835a675bbea32219f2f2. Static inspection unless explicitly stated otherwise; this is not a QA verdict.

Separate product implementation from operator rollout

The maintainer's existing comment demonstrates a concrete stale-skill consequence (--project <cwd-or-inferred> versus semantic project ID). Source inspection also confirms that .githooks/pre-push currently removes and copies the Claude skill directory; it does not implement this issue's digest-bound, backed-up symlink rollout.

The issue remains valid, but its acceptance includes operator-side actions that this team must not assume authorized: exact installed preimages, approved supported destinations, stable canonical checkout, digest-bound replacement approval, runtime discovery and rollback receipts. The historical digests in the body are not current approval.

Before marking the full issue ready, record the supported destination/ownership policy and split or explicitly distinguish: (a) product-owned mechanism plus tests in temporary homes, which agents can implement once specified; (b) actual installed-directory replacements, which remain gated by current inventory and digest-bound approval. Do not close this issue merely because a fixture test passes; do not vendor the skill into another repository or execute pre-push installation against the real home.