fix(install): rewrite in-package relative links to apm_modules/ paths (#1147)

[danielmeppiel]

TL;DR

Fixes #1147. Sibling references from instructions/prompts/agents/commands to in-package assets (e.g. [guide](../../standards/style.md)) used to be deployed verbatim. After the .agents/.github split (#1103), those paths point nowhere because each primitive type now lands at a host-tool-specific destination that no longer matches the package's authoring layout. UnifiedLinkResolver now rewrites any in-package relative markdown link to point at the package's install location under apm_modules/ at install time.

Problem (WHY)

APM's deploy layout is host-tool-determined, not package-determined. A single APM package may ship instructions, prompts, agents, and skills, and each type lands at a different destination per target:

• .github/instructions/, .github/prompts/, .github/agents/ (Copilot)
• .agents/skills/ (cross-tool, post-feat(install): add --target agent-skills for cross-client .agents/skills/ deployment #1103)
• .cursor/rules/ (Cursor), and so on

Intra-package relative references in primitive bodies cross this routing boundary and break by design. PR #1103 made the breakage user-visible because skills moved out of the host's root, but the underlying constraint has always existed for cross-target installs.

UnifiedLinkResolver already rewrites links at install time, but only for .context.md/.memory.md files (hardcoded extension allow-list). It did not cover SKILL.md bodies, agents, prompts, or arbitrary asset paths.

Approach (WHAT)

Generalize UnifiedLinkResolver._rewrite_markdown_links so that, at install time only, any markdown link whose resolved target lands inside the source package gets rewritten to its apm_modules/ location in the consumer.

Scope:

• Install only — the compile path is deliberately untouched. Compile receives synthetic source dirs without per-link package provenance, so the same logic doesn't apply.
• Authoritative package_root — passed from package_info.install_path, so ADO 4-segment deps, virtual subdirs, monorepos, and local _local/<name>/ packages all work without shape inference.
• Containment — uses the existing ensure_path_within helper from path_security, which handles symlinks and Windows extended-prefix paths.
• Conservative skip-list — fragment-only links (#section), scheme links (http:, mailto:), root-absolute paths (/foo), and any link whose resolved target escapes the package root are left untouched.

Implementation (HOW)

• src/apm_cli/compilation/link_resolver.py

  • LinkResolutionContext gains package_root: Path | None and enable_asset_rewrite: bool (defaults to compile-safe).
  • UnifiedLinkResolver.__init__ accepts an optional package_root field.
  • resolve_links_for_installation populates package_root and sets enable_asset_rewrite=True.
  • resolve_links_for_compilation explicitly passes package_root=None, enable_asset_rewrite=False.
  • _rewrite_markdown_links keeps the existing context-file branch and adds an in-package asset branch behind the new flags.
  • New helpers: _is_rewritable_relative_link, _split_link_target (preserves #fragment / ?query), _resolve_in_package_asset_link. The new helper is intentionally isolated from _resolve_context_link to prevent regression.

• src/apm_cli/integration/base_integrator.py

  • init_link_resolver sets self.link_resolver.package_root = Path(scan_root) only when scan_root equals package_info.install_path. The narrowed-scan_root cases (e.g. $HOME/.apm/ for user scope) intentionally skip this so asset links cannot escape the .apm/ boundary.

Validation evidence

• Lint: uv run --extra dev ruff check src/ tests/ and uv run --extra dev ruff format --check src/ tests/ both silent.
• Unit tests: full uv run --extra dev pytest tests/unit -q -> 7684 passed.
• Integration: uv run --extra dev pytest tests/integration/test_local_install.py -q -> 18 passed (includes the new TestLocalInstallSiblingLinkRewriting::test_sibling_link_is_rewritten_to_apm_modules which reproduces [BUG] Package relative paths broken due to .agents and .github splitting #1147 end-to-end via apm install).
• Manual end-to-end repro (/tmp/apm-1147-repro/) confirmed: deployed instruction now contains ../../apm_modules/_local/producer/standards/style.md and that path resolves on disk.

New test coverage

• 10 new unit tests in tests/unit/compilation/test_link_resolver.py:
  • Happy-path rewrite to apm_modules/.
  • Missing-on-disk targets preserved (no false-positive rewrite).
  • Escape-package-root preserved (security: cannot point out of source package).
  • Fragment-only links and ?query suffixes preserved.
  • URL-scheme and root-absolute links left untouched.
  • Subdirectory packages (virtual subdir / ADO 4-segment) contained correctly.
  • Opt-out when package_root is unset.
  • Regression guard: compile path is NOT broadened.
• 1 integration test reproducing [BUG] Package relative paths broken due to .agents and .github splitting #1147 via real apm install.

How to test

mkdir -p /tmp/apm-1147 && cd /tmp/apm-1147
cat > producer/apm.yml <<'YML'
name: producer
version: 1.0.0
YML
mkdir -p producer/.apm/instructions producer/standards
echo "# Style guide" > producer/standards/style.md
cat > producer/.apm/instructions/foo.instructions.md <<'MD'
---
applyTo: "**/*.py"
---
# Foo

Follow the [style guide](../../standards/style.md).
MD

mkdir -p consumer/.github
cat > consumer/apm.yml <<'YML'
name: consumer
version: 1.0.0
dependencies:
  apm: []
YML

cd consumer
apm install ../producer
grep -F 'apm_modules/_local/producer/standards/style.md' .github/instructions/foo.instructions.md

Trade-offs

• Install-time warning for unresolved in-package links is deferred to a follow-up PR. The current DiagnosticCollector would surface one warning per primitive, which would spam typical installs. A separate aggregation design is needed.
• Markdown title syntax ([text](path "title")) passes through unchanged — supported but not stripped/re-emitted.
• Compile path is intentionally not broadened. Compile lacks per-link provenance about which source package a link came from, and the compile output is consumed differently than installed primitives.

Closes #1147.

[Copilot]

Pull request overview

This PR fixes broken relative markdown links between APM package primitives (instructions/prompts/agents/commands) and in-package assets by rewriting eligible in-package relative links at install time to point at the package's installed location under apm_modules/, preserving link functionality across host-tool-specific deploy directories.

Changes:

• Extend UnifiedLinkResolver to optionally rewrite in-package relative markdown links during installation (guarded by package_root + an enable flag).
• Wire BaseIntegrator.init_link_resolver() to set the authoritative package_root for install-time rewriting.
• Add unit + integration coverage, new user documentation, and a changelog entry for #1147.

Show a summary per file

File	Description
src/apm_cli/compilation/link_resolver.py	Adds install-time in-package asset link rewriting logic gated by package_root/flags.
src/apm_cli/integration/base_integrator.py	Sets link_resolver.package_root when scanning the full installed package root.
tests/unit/compilation/test_link_resolver.py	Adds unit tests for the new install-time rewrite behavior and compile-path regression coverage.
tests/integration/test_local_install.py	Adds an end-to-end repro asserting sibling link rewrite works after apm install.
docs/src/content/docs/guides/package-relative-links.md	Documents the package-relative link rewrite contract and caveats.
CHANGELOG.md	Adds a Fixed entry describing the #1147 behavior change.

Copilot's findings

• Files reviewed: 6/6 changed files
• Comments generated: 3

[danielmeppiel]

Good catch -- this was a real bug. Fixed in ce91ce3: _split_link_target now picks the earliest occurrence of # or ? so a combined doc.md?x=1#sec preserves the full ?x=1#sec suffix on the rewritten target. Added test_preserve_query_and_fragment_on_rewritten_link covering the combined case (passes locally with the rest of the resolver suite).

[danielmeppiel]

Adopted in ce91ce3 -- explicit assert match is not None, ... before .group(1) so a regex miss surfaces a clear failure message instead of an opaque AttributeError.

[danielmeppiel]

Shortened in ce91ce3 to one line per repo convention: Rewrite in-package relative markdown links to their apm_modules/ location at install time so sibling references survive the .agents/.github deploy split. (#1147).