fix(port): resolve nested generated resource links (#113)

Amp-Thread-ID: https://ampcode.com/threads/T-019f84ff-bc93-75ca-a36b-4e7561bc3f1d

Co-authored-by: Amp <amp@ampcode.com>

Author: oliver-kriska

CHANGELOG.md

@@ -116,6 +116,11 @@ capabilities rather than claiming cross-runtime feature parity.
 
 ### Fixed
 
+- **Generated nested resource links now resolve from their containing file** —
+  Amp, Codex, Pi, and OpenCode projections compute skill-relative paths from
+  each Markdown resource directory instead of the skill root, fixing broken
+  cross-skill and sibling links under nested `references/` directories.
+
 - **Reliable behavioral trigger gates and routing boundaries** — deterministic
   structural evals no longer depend on ignored local result caches, while
   `make eval-full` runs a fresh Claude Haiku 4.5 gate requiring every skill to

scripts/generated_target_snapshots.json

@@ -4,22 +4,22 @@
     "amp": {
       "entries": 379,
       "files": 251,
-      "sha256": "f233f4ba7205bdfd9cb9f8d15e341a600aa78c9a85dfbe5e228232ca4b3ccc59"
+      "sha256": "6e11b750d92f2fb45fcb996b877e81e7d4baac0a52115f4f250efd3d1fbe2100"
     },
     "codex": {
       "entries": 385,
       "files": 254,
-      "sha256": "210763516017a01a72d3d229702c57263a00956fbb87f05c6ff34554e3ee8311"
+      "sha256": "7d3384f5164dea6204d76229eeb42654d6352151784714452d8973ff10879d85"
     },
     "opencode": {
       "entries": 379,
       "files": 251,
-      "sha256": "a429a213023ced972b20f0bc592bf9346c55b7dbfd14dbf751dd4f91f941564a"
+      "sha256": "4952d736ff166d09ea6f2248035e207098ac4648372f75036330a7f125af684a"
     },
     "pi": {
       "entries": 380,
       "files": 252,
-      "sha256": "e670441b98013c6f0ce57fb7591a4c62730f277338f9cf4dd433a30806ad3ea6"
+      "sha256": "8c87793a75c47958091d71b9a8f89a543682b7a90f8dc35e78a9c984143b8678"
     }
   }
 }

scripts/port_lib/amp.py

@@ -94,6 +94,7 @@ def _target_relative_path(
     source_path: Path,
     current: SkillSource,
     skills: list[SkillSource],
+    source_file: Path,
 ) -> str:
     """Map a canonical resource path to its generated relative location."""
     by_source_dir = {skill.source_dir.resolve(): skill for skill in skills}
@@ -115,7 +116,8 @@ def _target_relative_path(
 
     relative_resource = resolved.relative_to(owner.source_dir.resolve())
     generated_resource = Path(owner.target_name) / relative_resource
-    generated_current = Path(current.target_name)
+    source_relative = source_file.resolve().relative_to(current.source_dir.resolve())
+    generated_current = Path(current.target_name) / source_relative.parent
     return Path(os.path.relpath(generated_resource, generated_current)).as_posix()
 
 
@@ -137,7 +139,7 @@ def replace_skill_dir(match: re.Match[str]) -> str:
             raise ValueError(
                 f"{source_file}: missing referenced resource {source_path}"
             )
-        return _target_relative_path(source_path, current, skills)
+        return _target_relative_path(source_path, current, skills, source_file)
 
     def replace_plugin_root(match: re.Match[str]) -> str:
         raw_path = match.group(1)
@@ -153,19 +155,19 @@ def replace_plugin_root(match: re.Match[str]) -> str:
             raise ValueError(
                 f"{source_file}: unsupported CLAUDE_PLUGIN_ROOT resource {source_path}"
             )
-        return _target_relative_path(source_path, current, skills)
+        return _target_relative_path(source_path, current, skills, source_file)
 
     def replace_bare_sibling(match: re.Match[str]) -> str:
         source_path = current.source_dir.parent / match.group(1) / match.group(2)
         if "<" in match.group(0) or ">" in match.group(0) or not source_path.exists():
             return match.group(0)
-        return _target_relative_path(source_path, current, skills)
+        return _target_relative_path(source_path, current, skills, source_file)
 
     def replace_canonical_skill_path(match: re.Match[str]) -> str:
         source_path = current.source_dir.parent / match.group(1) / match.group(2)
         if "<" in match.group(0) or ">" in match.group(0) or not source_path.exists():
             return match.group(0)
-        return _target_relative_path(source_path, current, skills)
+        return _target_relative_path(source_path, current, skills, source_file)
 
     def replace_bare_skill_path(match: re.Match[str]) -> str:
         source_skill = current.source_dir.parent / match.group(1)
@@ -177,7 +179,7 @@ def replace_bare_skill_path(match: re.Match[str]) -> str:
             or not source_path.exists()
         ):
             return match.group(0)
-        return _target_relative_path(source_path, current, skills)
+        return _target_relative_path(source_path, current, skills, source_file)
 
     text = SKILL_DIR_TOKEN_RE.sub(replace_skill_dir, text)
     text = PLUGIN_ROOT_TOKEN_RE.sub(replace_plugin_root, text)

scripts/port_lib/codex.py

@@ -1358,6 +1358,7 @@ def _target_relative_path(
     source_path: Path,
     current: SkillSource,
     skills: list[SkillSource],
+    source_file: Path,
 ) -> str:
     resolved = source_path.resolve()
     owner = next(
@@ -1378,8 +1379,10 @@ def _target_relative_path(
     generated_resource = (
         Path(owner.target_name) / resolved.relative_to(owner.source_dir.resolve())
     )
+    source_relative = source_file.resolve().relative_to(current.source_dir.resolve())
+    generated_current = Path(current.target_name) / source_relative.parent
     return Path(
-        os.path.relpath(generated_resource, Path(current.target_name))
+        os.path.relpath(generated_resource, generated_current)
     ).as_posix()
 
 
@@ -1398,7 +1401,7 @@ def replace_skill_dir(match: re.Match[str]) -> str:
         source_path = current.source_dir / raw_path
         if not source_path.exists():
             raise ValueError(f"{source_file}: missing referenced resource {source_path}")
-        return _target_relative_path(source_path, current, skills)
+        return _target_relative_path(source_path, current, skills, source_file)
 
     def replace_plugin_root(match: re.Match[str]) -> str:
         raw_path = match.group(1)
@@ -1411,19 +1414,19 @@ def replace_plugin_root(match: re.Match[str]) -> str:
             raise ValueError(
                 f"{source_file}: unsupported CLAUDE_PLUGIN_ROOT resource {source_path}"
             )
-        return _target_relative_path(source_path, current, skills)
+        return _target_relative_path(source_path, current, skills, source_file)
 
     def replace_bare_sibling(match: re.Match[str]) -> str:
         source_path = current.source_dir.parent / match.group(1) / match.group(2)
         if "<" in match.group(0) or ">" in match.group(0) or not source_path.exists():
             return match.group(0)
-        return _target_relative_path(source_path, current, skills)
+        return _target_relative_path(source_path, current, skills, source_file)
 
     def replace_canonical_skill_path(match: re.Match[str]) -> str:
         source_path = current.source_dir.parent / match.group(1) / match.group(2)
         if "<" in match.group(0) or ">" in match.group(0) or not source_path.exists():
             return match.group(0)
-        return _target_relative_path(source_path, current, skills)
+        return _target_relative_path(source_path, current, skills, source_file)
 
     def replace_bare_skill_path(match: re.Match[str]) -> str:
         source_skill = current.source_dir.parent / match.group(1)
@@ -1435,7 +1438,7 @@ def replace_bare_skill_path(match: re.Match[str]) -> str:
             or not source_path.exists()
         ):
             return match.group(0)
-        return _target_relative_path(source_path, current, skills)
+        return _target_relative_path(source_path, current, skills, source_file)
 
     text = SKILL_DIR_TOKEN_RE.sub(replace_skill_dir, text)
     text = PLUGIN_ROOT_TOKEN_RE.sub(replace_plugin_root, text)

scripts/tests/test_amp.py

@@ -132,7 +132,7 @@ def test_build_rewrites_verified_bare_resource_paths(tmp_path) -> None:
     assert "../phx-second/scripts/run.sh" in generated
     assert "plugins/elixir-phoenix" not in generated
     nested = (output / "phx-first" / "references" / "nested.md").read_text()
-    assert "../phx-second/references/guide.md" in nested
+    assert "../../phx-second/references/guide.md" in nested
 
 
 def test_build_rejects_name_collisions_before_replacing_output(tmp_path) -> None:

scripts/tests/test_codex.py

@@ -248,12 +248,21 @@ def test_rewrites_cross_skill_resources_and_rejects_missing_or_escaping_paths(
     second = _write_skill(plugin, "second", "phx:second")
     (second / "references").mkdir()
     (second / "references" / "guide.md").write_text("Guide\n", encoding="utf-8")
+    first_references = plugin / "skills" / "first" / "references"
+    first_references.mkdir()
+    (first_references / "nested.md").write_text(
+        "Read `second/references/guide.md`.\n",
+        encoding="utf-8",
+    )
 
     output = tmp_path / "codex"
     codex.build(plugin, output)
     assert "../phx-second/references/guide.md" in (
         output / "skills" / "phx-first" / "SKILL.md"
     ).read_text()
+    assert "../../phx-second/references/guide.md" in (
+        output / "skills" / "phx-first" / "references" / "nested.md"
+    ).read_text()
 
     missing = tmp_path / "missing"
     broken = _write_skill(

targets/amp/skills/phx-compound/references/compound-workflow.md

@@ -93,14 +93,14 @@ Gathering strategy:
 
 ### Phase 4: Schema Validation
 
-Validate frontmatter against `../compound-docs/references/schema.md`.
+Validate frontmatter against `../../compound-docs/references/schema.md`.
 Use suggested values when they fit; create descriptive labels when
 they don't. Only `severity` is a strict enum.
 
 ### Phase 5: File Creation
 
 Create in `.claude/solutions/{category}/` using the template from
-`../compound-docs/references/resolution-template.md`.
+`../../compound-docs/references/resolution-template.md`.
 
 Filename: `{sanitized-symptom}-{module}-{YYYYMMDD}.md`
 

targets/amp/skills/phx-deps-audit/references/cassettes.md

@@ -30,7 +30,7 @@ endpoints those rules consume.
 ## Cassette layout
 
 ```text
-test-assets/hex-api-cassettes
+../test-assets/hex-api-cassettes
 ├── phoenix.packages.json
 ├── phoenix.releases.1.7.20.json
 ├── phoenix.releases.1.7.21.json
@@ -98,7 +98,7 @@ Mirrors `hex.pm` API verbatim (only fields we consume):
 # Helper script — capture.sh
 pkg=$1
 ver=$2
-out_dir=test-assets/hex-api-cassettes
+out_dir=../test-assets/hex-api-cassettes
 
 curl -fsSL "https://hex.pm/api/packages/${pkg}" \
   | jq '.' > "${out_dir}/${pkg}.packages.json"
@@ -238,8 +238,8 @@ When a user adds a `hex_vet.exs` entry for a package without a
 cassette, document the manual flow in the PR:
 
 ```bash
-bash priv/cassettes/capture.sh <pkg> <ver>
-git add test-assets/hex-api-cassettes
+bash ../priv/cassettes/capture.sh <pkg> <ver>
+git add ../test-assets/hex-api-cassettes
 ```
 
 Reviewers should diff the cassette body and the `_meta.json` SHA

targets/amp/skills/phx-deps-audit/references/differential.md

@@ -98,7 +98,7 @@ benefit from differential mode (the package itself is the unit).
 Once both NDJSON streams exist, the skill body invokes:
 
 ```bash
-python3 "scripts/diff_findings.py" \
+python3 "../scripts/diff_findings.py" \
     --new  "${AUDIT_TMPDIR}/findings.jsonl" \
     --old  "${AUDIT_TMPDIR}/findings.old.jsonl" \
     --new-out     "${AUDIT_TMPDIR}/new_signals.jsonl" \

targets/amp/skills/phx-deps-audit/references/hook.md

@@ -69,7 +69,7 @@ next hook invocation gets a Tier 0 hit.
 ## Policy enforcement
 
 The hook reads `policy.block_on_unvetted` from `hex_vet.exs` (see
-`../phx-deps-vet/references/hex-vet.md` for the tri-mode schema) and gates
+`../../phx-deps-vet/references/hex-vet.md` for the tri-mode schema) and gates
 findings accordingly:
 
 | Mode | On Tier 1 findings |