bigpowers 2.77.0 → 2.77.1

package/scripts/check-skill-links.py

@@ -0,0 +1,78 @@
+#!/usr/bin/env python3
+# check-skill-links.py — fail on machine-absolute paths or dangling relative
+# links in skill docs. Scans skills/**/SKILL.md and .pi/skills/**/SKILL.md.
+# Run: python3 scripts/check-skill-links.py  (exit 1 with a report on failure)
+#
+# NOTE: .cursor/rules/ and .gemini/extensions/ are intentionally excluded.
+# Those trees are auto-generated from SKILL.md sources via sync-skills.sh and
+# are not published to npm, so dangling links there are a rendering gap, not a
+# source defect. Enable once the sync pipeline gains link-rewriting support.
+# See: https://github.com/danielvm-git/bigpowers/issues/78
+import glob
+import os
+import sys
+
+# Import shared patterns — single source of truth so the rewriter (srp-engine)
+# and the gate always agree on what constitutes a "link".
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from lib.link_utils import LINK_RE, EXTERNAL_RE, MACHINE_PATH_RE, strip_code_spans  # noqa: E402
+
+
+def resolve_repo_root() -> str:
+    here = os.path.dirname(os.path.abspath(__file__))
+    candidate = os.path.dirname(here)  # scripts/ -> repo root
+    if os.path.isdir(os.path.join(candidate, "skills")):
+        return candidate
+    return os.getcwd()
+
+
+def check_file_links(smd: str, root: str) -> list[str]:
+    """Return a list of problem strings for a single SKILL.md file."""
+    rel = os.path.relpath(smd, root)
+    with open(smd, encoding="utf-8") as f:
+        text = f.read()
+
+    problems = []
+
+    # Machine-absolute path check runs on raw text (line-by-line for location).
+    for i, line in enumerate(text.splitlines(), 1):
+        if MACHINE_PATH_RE.search(line):
+            problems.append(f"{rel}:{i}: machine-absolute path: {line.strip()[:100]}")
+
+    # Link check runs on shadow (code spans blanked) to avoid false positives
+    # on example paths shown inside fenced blocks or inline code.
+    shadow = strip_code_spans(text)
+    for m in LINK_RE.finditer(shadow):
+        target = m.group(2).split("#", 1)[0]  # strip fragment
+        if not target or EXTERNAL_RE.match(target) or target.startswith(("#", "/")):
+            continue
+        resolved = os.path.normpath(os.path.join(os.path.dirname(smd), target))
+        if not os.path.exists(resolved):
+            problems.append(f"{rel}: dangling link -> {target}")
+
+    return problems
+
+
+def check(root: str) -> list[str]:
+    problems = []
+    for tree in ("skills", os.path.join(".pi", "skills")):
+        pattern = os.path.join(root, tree, "*", "SKILL.md")
+        for smd in sorted(glob.glob(pattern)):
+            problems.extend(check_file_links(smd, root))
+    return problems
+
+
+def main() -> int:
+    root = resolve_repo_root()
+    problems = check(root)
+    if problems:
+        print(f"check-skill-links: {len(problems)} problem(s):")
+        for p in problems:
+            print(f"  {p}")
+        return 1
+    print("check-skill-links: OK — no machine paths or dangling links")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/generate-reference-tables.sh

@@ -32,10 +32,11 @@ BLOCK="<!-- AUTO-GENERATED-CATALOG: begin — do not edit manually; run scripts/
 for row in "${ROWS[@]}"; do
   skill="${row%% *}"
   model="${row##* }"
+  skill_rel="${skill#$REPO_ROOT/}"
   # capitalise first letter for display
   model_cap="$(echo "${model:0:1}" | tr '[:lower:]' '[:upper:]')${model:1}"
   BLOCK+="
-| \`$skill\` | **$model_cap** |"
+| \`$skill_rel\` | **$model_cap** |"
 done
 BLOCK+="
 

package/scripts/lib/link_utils.py

@@ -0,0 +1,49 @@
+#!/usr/bin/env python3
+"""link_utils.py — shared Markdown link patterns used by srp-engine and check-skill-links.
+
+Single source of truth for what constitutes a "link" so the rewriter and the
+regression gate always agree on the definition.
+"""
+import re
+
+# Matches standard Markdown links — with or without an optional title attribute.
+#   [text](target)
+#   [text](target "title")
+# Group 1: link text, Group 2: raw target (may include URL fragment)
+LINK_RE = re.compile(
+    r'\[([^\]]*)\]\('       # [text](
+    r'([^)\s"]+)'           # target (no spaces, no quotes)
+    r'(?:\s+"[^"]*")?'      # optional title attribute: "title text"
+    r'\s*\)'                # closing )
+)
+
+# Matches scheme-prefixed (non-relative) URLs that should never be rewritten
+# or resolved as local file paths.
+EXTERNAL_RE = re.compile(r'(?i)^(https?|ftp|file|mailto):')
+
+# Detects machine-absolute paths that must not appear in skill docs.
+# Covers macOS (/Users/), Linux (/home/), and Windows (C:\Users, D:\Users …).
+MACHINE_PATH_RE = re.compile(r'file:///|/Users/|/home/|[A-Z]:\\Users')
+
+# ---------------------------------------------------------------------------
+# Markdown code-block stripping
+# ---------------------------------------------------------------------------
+
+# Fenced code block: ``` or ~~~ with optional language tag, any content, close fence.
+_FENCED_BLOCK_RE = re.compile(r'(?m)^(`{3,}|~{3,})[^\n]*\n.*?\n\1\s*$', re.DOTALL)
+# Inline code: `…` (single backtick, non-empty)
+_INLINE_CODE_RE = re.compile(r'`[^`\n]+`')
+
+
+def strip_code_spans(text: str) -> str:
+    """Return *text* with fenced blocks and inline code replaced by blank space.
+
+    Preserves original character positions so that any offset-based logic
+    remains valid; only the link-matching content is neutralised.
+    """
+    def _blank(m: re.Match) -> str:
+        return ' ' * len(m.group(0))
+
+    text = _FENCED_BLOCK_RE.sub(_blank, text)
+    text = _INLINE_CODE_RE.sub(_blank, text)
+    return text

package/scripts/lib/srp-engine.py

@@ -7,6 +7,83 @@ import glob
 import subprocess
 import yaml
 
+# Ensure scripts/lib is on the path so link_utils resolves regardless of cwd.
+_LIB_DIR = os.path.dirname(os.path.abspath(__file__))
+if _LIB_DIR not in sys.path:
+    sys.path.insert(0, _LIB_DIR)
+
+from link_utils import LINK_RE, EXTERNAL_RE, strip_code_spans  # noqa: E402
+
+def rewrite_links_for_pi(body, name):
+    """Repoint relative links so they resolve from .pi/skills/<name>/.
+
+    Sibling *.md content is inlined into the rendered SKILL.md body, but the
+    links to those files (and to repo-root docs) still point at paths relative
+    to the source dir, so they dangle in the rendered tree. Repoint them at
+    the shipped source tree (skills/, profiles/, repo-root files) so links
+    resolve in repo checkouts and npm installs alike. External, anchor, and
+    absolute links pass through untouched.
+
+    Code fences and inline code are skipped — links inside them are examples,
+    not navigation targets.
+    """
+    out_dir = os.path.join(".pi", "skills", name)
+    # Build a "shadow" copy with code spans blanked out so LINK_RE never
+    # matches inside ``` blocks or inline `code`.
+    shadow = strip_code_spans(body)
+
+    def repl(m):
+        # If this match falls inside a code span the shadow char is a space;
+        # the real body char at that position is not a '[' — so LINK_RE won't
+        # match in the shadow at all.  The sub() runs on the shadow but we
+        # return the replacement for the real body using the captured groups.
+        text, raw_target = m.group(1), m.group(2).strip()
+        if EXTERNAL_RE.match(raw_target) or raw_target.startswith(('#', '/')):
+            return m.group(0)
+        # Split fragment before normpath to avoid mangling '#section/sub'.
+        if '#' in raw_target:
+            path_part, fragment = raw_target.split('#', 1)
+            frag_suffix = '#' + fragment
+        else:
+            path_part, frag_suffix = raw_target, ''
+        resolved = os.path.normpath(os.path.join("skills", name, path_part))
+        if resolved.startswith(".."):
+            return m.group(0)  # escapes repo root; leave untouched
+        new_target = os.path.relpath(resolved, out_dir).replace(os.sep, '/') + frag_suffix
+        return f"[{text}]({new_target})"
+
+    return LINK_RE.sub(repl, shadow).replace(shadow, body) if shadow == body else _apply_repl_on_real(body, shadow, name, out_dir)
+
+
+def _apply_repl_on_real(body, shadow, name, out_dir):
+    """Apply link rewrites to *body* using *shadow* to skip code spans.
+
+    Iterates LINK_RE matches on *shadow* (which has code spans blanked) and
+    rebuilds body with only the matched positions replaced.
+    """
+    result = []
+    last = 0
+    for m in LINK_RE.finditer(shadow):
+        result.append(body[last:m.start()])
+        text, raw_target = m.group(1), m.group(2).strip()
+        if EXTERNAL_RE.match(raw_target) or raw_target.startswith(('#', '/')):
+            result.append(body[m.start():m.end()])
+        else:
+            if '#' in raw_target:
+                path_part, fragment = raw_target.split('#', 1)
+                frag_suffix = '#' + fragment
+            else:
+                path_part, frag_suffix = raw_target, ''
+            resolved = os.path.normpath(os.path.join("skills", name, path_part))
+            if resolved.startswith(".."):
+                result.append(body[m.start():m.end()])
+            else:
+                new_target = os.path.relpath(resolved, out_dir).replace(os.sep, '/') + frag_suffix
+                result.append(f"[{text}]({new_target})")
+        last = m.end()
+    result.append(body[last:])
+    return ''.join(result)
+
 def resolve_repo_root():
     lib_dir = os.path.dirname(os.path.abspath(__file__))
     # scripts/lib/srp-engine.py -> two levels up is REPO_ROOT
@@ -210,7 +287,11 @@ def main():
                 continue
 
             for adapter in adapters:
-                dispatch_to_adapter(skill_data, adapter, repo_root)
+                data = skill_data
+                if adapter == "pi":
+                    data = dict(skill_data)
+                    data["body_pi_skill"] = rewrite_links_for_pi(skill_data['body'], skill_data['name'])
+                dispatch_to_adapter(data, adapter, repo_root)
 
             if okf_mode:
                 render_okf_concept(skill_data, okf_wiki_skills)
@@ -235,6 +316,10 @@ def main():
 
     skill_data = parse_skill(skill_md_path)
 
+    if target == "pi":
+        skill_data = dict(skill_data)
+        skill_data["body_pi_skill"] = rewrite_links_for_pi(skill_data['body'], skill_data['name'])
+
     if dry_run or not target:
         print(json.dumps(skill_data, indent=2))
         return

package/skills/audit-code/SKILL.md

@@ -31,7 +31,7 @@ Apply the full checklist to churn-ranked files in descending order. Files with z
 - Default: full checklist
 - --quick: Run only Supply Chain and Test Coverage. Use for changes under 50 LOC.
 - --gate: Non-interactive mode for automated CI gating (used by build-epic step 6). Exit with non-zero status code (`exit 1`) on ANY checklist failure; `exit 0` only if ALL items pass. Produces a compact pass/fail summary to stderr. On failure, list every ✗ item with reason.
-- --parallel: Run checklist sections in **isolated git worktrees** (e45s18) so concurrent checks cannot corrupt each other's working tree. See [REFERENCE.md](REFERENCE.md) or:
+- --parallel: Run checklist sections in **isolated git worktrees** (e45s18) so concurrent checks cannot corrupt each other's working tree:
 
 ```bash
 bash scripts/lib/parallel-review-worktrees.sh audit-code

package/skills/craft-skill/SKILL.md

@@ -33,7 +33,7 @@ Move process detail into the SKILL.md body or REFERENCE.md — never into `descr
    - Any reference materials to include?
    - What specs/ output does it produce (if any)?
 
-2. **Verify Principles** — Ensure the skill aligns with [PRINCIPLES.md](../docs/PRINCIPLES.md):
+2. **Verify Principles** — Ensure the skill aligns with [PRINCIPLES.md](https://github.com/danielvm-git/bigpowers/blob/main/docs/PRINCIPLES.md):
    - Is it atomic (verb-noun)?
    - Is it "deep" (simple interface, complex internal logic)?
    - Does it include Hard Gates?
@@ -46,7 +46,7 @@ Move process detail into the SKILL.md body or REFERENCE.md — never into `descr
 
    **Auto-skill from library README:** When user provides a library README or API docs URL, extract: triggers, HARD GATEs, verify commands, specs/ output — draft SKILL.md without inventing APIs not in the source.
 
-4. Add `model:` frontmatter (`haiku` | `sonnet` | `opus`) per [model-profiles.md](../docs/references/model-profiles.md).
+4. Add `model:` frontmatter (`haiku` | `sonnet` | `opus`) per [model-profiles.md](https://github.com/danielvm-git/bigpowers/blob/main/docs/references/model-profiles.md).
 
 > **STREAM CONTINUITY** — When writing file content, output in continuous chunks of ~200 lines. Do not pause. Continue immediately until complete. If you need time, emit a placeholder comment rather than going silent.
 

package/skills/elaborate-spec/SKILL.md

@@ -65,7 +65,7 @@ Once the user has answered the main questions, probe for assumptions:
 
 ### 4. Synthesize and confirm
 
-Summarize your understanding in 3–5 bullet points aligned with [countable-story-format.md](file:///Users/danielvm/Developer/bigpowers/countable-story-format.md):
+Summarize your understanding in 3–5 bullet points aligned with [countable-story-format.md](https://github.com/danielvm-git/bigpowers/blob/main/docs/countable-story-format.md):
 - The problem (feeds into §1 Business narrative)
 - The solution and main flow (feeds into §5)
 - The key constraints and alternative flows (feeds into §6)

package/skills/evolve-skill/REFERENCE.md

@@ -9,4 +9,4 @@
 **Evidence:** path/to/benchmark-report.md
 ```
 
-Benchmark repo: `/Users/danielvm/Developer/bigpowers-benchmark/`
+Benchmark repo: `bigpowers-benchmark` — resolve the local clone on this machine (e.g. `gh repo clone danielvm-git/bigpowers-benchmark` if absent); never assume a hard-coded absolute path.

package/skills/grill-me/REFERENCE.md

@@ -43,7 +43,7 @@ Ask one question at a time. For each challenge, cite the specific URL and sectio
 
 When an assumption doesn't match the docs:
 
-> "Your plan uses `library.doThing(a, b)` but the [docs](URL) show the signature is `doThing(config: {a, b})` with a config object. This will fail at runtime."
+> "Your plan uses `library.doThing(a, b)` but the [docs](https://example.com/api-reference) show the signature is `doThing(config: {a, b})` with a config object. This will fail at runtime."
 
 Document each discrepancy clearly.
 

package/skills/guard-git/SKILL.md

@@ -22,7 +22,7 @@ Installs a shared hook that blocks destructive git operations and enforces workf
 ## Quick start
 
 1. **Scope**: ask project-only vs global (paths differ per product).
-2. **Copy the hook bundle** from the root [hooks/](hooks/) directory to the client's hooks directory.
+2. **Write the hook bundle** from [REFERENCE.md](REFERENCE.md) into the client's hooks directory.
 3. **Run `chmod +x`** on `pre-tool-use.sh`.
 4. **Merge** the hook snippet from [REFERENCE.md](REFERENCE.md) into the right settings file — do not wipe unrelated keys.
 5. **Verify** with the tests in [REFERENCE.md](REFERENCE.md).

package/skills/investigate-bug/SKILL.md

@@ -124,6 +124,6 @@ After writing the bug file, print a one-line summary of the root cause and sugge
 
 <!-- story: e35s10 -->
 
-- [Feathers' Seams & Characterization Tests](../../docs/references/feathers.md) — seam types, characterization tests, and the legacy code change algorithm
-- [Fowler's Code Smells](../../docs/references/fowler.md) — identifying structural problems by smell before investigating
+- [Feathers' Seams & Characterization Tests](https://github.com/danielvm-git/bigpowers/blob/main/docs/references/feathers.md) — seam types, characterization tests, and the legacy code change algorithm
+- [Fowler's Code Smells](https://github.com/danielvm-git/bigpowers/blob/main/docs/references/fowler.md) — identifying structural problems by smell before investigating
 

package/skills/model-domain/CONTEXT-FORMAT.md

@@ -57,9 +57,9 @@ _Avoid_: Client, buyer, account
 
 ## Contexts
 
-- [Ordering](./src/ordering/CONTEXT.md) — receives and tracks customer orders
-- [Billing](./src/billing/CONTEXT.md) — generates invoices and processes payments
-- [Fulfillment](./src/fulfillment/CONTEXT.md) — manages warehouse picking and shipping
+- Ordering — `src/ordering/CONTEXT.md` — receives and tracks customer orders
+- Billing — `src/billing/CONTEXT.md` — generates invoices and processes payments
+- Fulfillment — `src/fulfillment/CONTEXT.md` — manages warehouse picking and shipping
 
 ## Relationships
 

package/skills/plan-refactor/SKILL.md

@@ -82,8 +82,8 @@ After writing `specs/REFACTOR_LATEST.md`, suggest running `kickoff-branch` next
 
 <!-- story: e35s10 -->
 
-- [Fowler's Refactoring Catalog](../../docs/references/fowler.md) — canonical refactoring vocabulary and code-smell taxonomy
-- [Beck's Tidy First?](../../docs/references/kent-beck.md) — structural change before behavioral change
+- [Fowler's Refactoring Catalog](https://github.com/danielvm-git/bigpowers/blob/main/docs/references/fowler.md) — canonical refactoring vocabulary and code-smell taxonomy
+- [Beck's Tidy First?](https://github.com/danielvm-git/bigpowers/blob/main/docs/references/kent-beck.md) — structural change before behavioral change
 
 ## Verify
 

package/skills/plan-release/SKILL.md

@@ -17,7 +17,7 @@ Synthesize the conversation context into `specs/release-plan.yaml` (index) and s
 |------|---------|
 | `specs/release-plan.yaml` | `release.version`, semver bump hint, WSJF-ordered epic list with `id`, `capsule_dir`, `wsjf`, `bcps` — **no story status** |
 | `specs/epics/eNN-<slug>/epic.yaml` | Epic manifest: `id`, `title`, `wsjf`, `total_bcps`, `status`, `stories[]` list |
-| `specs/epics/eNN-<slug>/eNNsYY-<slug>.md` | Story spec in [countable-story-format.md](file:///Users/danielvm/Developer/bigpowers/countable-story-format.md) with 20 sections and Gherkin acceptance criteria |
+| `specs/epics/eNN-<slug>/eNNsYY-<slug>.md` | Story spec in [countable-story-format.md](https://github.com/danielvm-git/bigpowers/blob/main/docs/countable-story-format.md) with 20 sections and Gherkin acceptance criteria |
 | `specs/epics/eNN-<slug>/eNNsYY-tasks.yaml` | Decoupled task checklist with `verify:` commands per task |
 | `specs/execution-status.yaml` | Flat key-value store for story status (`eNNsYY: todo`) |
 
@@ -102,7 +102,7 @@ stories:
 ```
 ### 6. Save story specs (countable-story-format .md)
 
-Each story becomes a standalone `.md` file following [countable-story-format.md](file:///Users/danielvm/Developer/bigpowers/countable-story-format.md). Minimum: maturity 3 (Countable) with all 20 sections present. Acceptance criteria in §17 use Gherkin scenarios.
+Each story becomes a standalone `.md` file following [countable-story-format.md](https://github.com/danielvm-git/bigpowers/blob/main/docs/countable-story-format.md). Minimum: maturity 3 (Countable) with all 20 sections present. Acceptance criteria in §17 use Gherkin scenarios.
 ### 7. Save decoupled task files (`-tasks.yaml`)
 
 Each story has a decoupled `-tasks.yaml` with implementation steps:

package/skills/using-bigpowers/SKILL.md

@@ -78,7 +78,7 @@ UTILITY     terse-mode / craft-skill / edit-document (any phase)
 
 If you work alone and do not want PR ceremony every task:
 
-1. Read [profiles/solo-git.md](../profiles/solo-git.md).
+1. Read [profiles/solo-git.md](../../profiles/solo-git.md).
 2. Register with `compose-workflow` → `specs/WORKFLOW-solo-git.md`.
 3. Ship with `release-branch` in **solo-local** mode (`land-branch.sh`), not `gh pr create`.
 

package/skills/write-document/REFERENCE.md

@@ -141,7 +141,7 @@ Auto-fill from CLAUDE.md `Test` and `Lint` commands.
 ```markdown
 ## Changelog
 
-See [CHANGELOG.md](CHANGELOG.md) or [Releases](https://github.com/user/repo/releases).
+See [CHANGELOG.md](../../CHANGELOG.md) or [Releases](https://github.com/user/repo/releases).
 ```
 
 ### 13. Links
@@ -158,7 +158,7 @@ See [CHANGELOG.md](CHANGELOG.md) or [Releases](https://github.com/user/repo/rele
 ```markdown
 ## License
 
-MIT — see [LICENSE](LICENSE) for details.
+MIT — see [LICENSE](../../LICENSE) for details.
 ```
 
 Detect from CLAUDE.md or project LICENSE file.

package/skills-lock.json

@@ -13,7 +13,7 @@
     },
     "audit-code": {
       "description": "Self-review checklist for the coding agent to run before dispatching a reviewer. Checks CONVENTIONS.md compliance, Boy Scout Rule, test coverage, types, and SOLID. Produces a pass/fail checklist. Use before request-review, before committing, or when user asks for a code quality check.",
-      "sha256": "bbb128254464f8f4",
+      "sha256": "0636f1d9d6c591a3",
       "path": "skills/audit-codeSKILL.md"
     },
     "audit-plan": {
@@ -48,7 +48,7 @@
     },
     "craft-skill": {
       "description": "Create new bigpowers skills with proper structure, progressive disclosure, and bundled resources. Use when user wants to create, write, or build a new skill for the bigpowers lifecycle.",
-      "sha256": "cbf8ab939cfbab87",
+      "sha256": "2caa9d8ae9298b4b",
       "path": "skills/craft-skillSKILL.md"
     },
     "deepen-architecture": {
@@ -108,7 +108,7 @@
     },
     "elaborate-spec": {
       "description": "Refine a rough idea into a clear, detailed specification through dialogue. Does not produce code. Use when user has a vague idea, wants to think through a feature before planning, or needs to turn \"I want X\" into a concrete spec.",
-      "sha256": "62ebfca87e6d0162",
+      "sha256": "9307ab61c789a0a0",
       "path": "skills/elaborate-specSKILL.md"
     },
     "enforce-first": {
@@ -158,7 +158,7 @@
     },
     "guard-git": {
       "description": "Block dangerous git commands (push, force push, reset --hard, clean, branch -D, checkout/restore .) and enforce Conventional Commits & Branch Protection before an AI agent runs them. Installs hook scripts for Claude Code, Cursor, Cursor CLI, and Gemini CLI; documents Google Antigravity Terminal deny lists. Use when the user wants git safety hooks, to block git push or destructive git in agents, or to mirror the same policy across AI coding tools.",
-      "sha256": "9ee881df89273b00",
+      "sha256": "e7083cba6d95a15f",
       "path": "skills/guard-gitSKILL.md"
     },
     "harden-vps": {
@@ -178,7 +178,7 @@
     },
     "investigate-bug": {
       "description": "Investigate a bug or issue by exploring the codebase to find root cause, then write a TDD-based fix plan to specs/bugs/BUG-*.md. Use when user reports a bug, wants to investigate a problem, mentions \"triage\", or wants to plan a fix.",
-      "sha256": "b842fd329d1f7741",
+      "sha256": "54f8c5417be34ef0",
       "path": "skills/investigate-bugSKILL.md"
     },
     "kickoff-branch": {
@@ -218,12 +218,12 @@
     },
     "plan-refactor": {
       "description": "Create a detailed refactor plan with tiny commits via user interview, then save it as specs/REFACTOR_LATEST.md. Use when user wants to plan a refactor, create a refactoring RFC, or break a refactor into safe incremental steps.",
-      "sha256": "c418c850806e2f16",
+      "sha256": "2d18809da7cc9de8",
       "path": "skills/plan-refactorSKILL.md"
     },
     "plan-release": {
       "description": "\"RELEASE-INDEX BUILDER — Sequence elaborated epics into specs/release-plan.yaml with WSJF ordering and BCP baselines. NOT a planning-spine substitute: it does not scope work (scope-work) or write story tasks (plan-work). Use after elaborate-spec when the user wants a versioned release index of epics.\"",
-      "sha256": "b56b800817cd383e",
+      "sha256": "9334ff48e5b1fab3",
       "path": "skills/plan-releaseSKILL.md"
     },
     "plan-tests": {
@@ -358,7 +358,7 @@
     },
     "using-bigpowers": {
       "description": "One-time bootstrap that introduces the bigpowers skills system, the PMBOK lifecycle arc, and tells you which skill to call first for your situation. Use when starting with bigpowers for the first time, when user asks \"where do I start?\", or when the skills system needs to be explained.",
-      "sha256": "332d6468868b759b",
+      "sha256": "bad9ebe9bf303b36",
       "path": "skills/using-bigpowersSKILL.md"
     },
     "validate-contracts": {

package/tests/test_srp_engine.py

@@ -0,0 +1,148 @@
+#!/usr/bin/env python3
+"""tests/test_srp_engine.py — unit tests for rewrite_links_for_pi and link_utils.
+
+Run: python3 -m pytest tests/test_srp_engine.py -v
+  or: python3 tests/test_srp_engine.py
+"""
+import os
+import sys
+import unittest
+
+# Make scripts/lib importable without installation.
+_REPO_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+_LIB = os.path.join(_REPO_ROOT, "scripts", "lib")
+sys.path.insert(0, _LIB)
+sys.path.insert(0, os.path.join(_REPO_ROOT, "scripts"))
+
+# srp-engine.py has a hyphen so we load it via importlib.
+import importlib.util as _ilu
+_spec = _ilu.spec_from_file_location("srp_engine", os.path.join(_LIB, "srp-engine.py"))
+_srp = _ilu.module_from_spec(_spec)
+sys.modules["srp_engine"] = _srp
+_spec.loader.exec_module(_srp)
+
+from srp_engine import rewrite_links_for_pi  # type: ignore[import]
+from link_utils import strip_code_spans, LINK_RE, MACHINE_PATH_RE
+
+
+class TestStripCodeSpans(unittest.TestCase):
+    def test_fenced_block_blanked(self):
+        md = "Before.\n```\n[fake](fake.md)\n```\nAfter."
+        shadow = strip_code_spans(md)
+        self.assertNotIn("[fake](fake.md)", shadow)
+        self.assertEqual(len(shadow), len(md))  # positions preserved
+
+    def test_inline_code_blanked(self):
+        md = "Use `[x](y.md)` as an example."
+        shadow = strip_code_spans(md)
+        self.assertNotIn("[x](y.md)", shadow)
+        self.assertEqual(len(shadow), len(md))
+
+    def test_real_link_survives(self):
+        md = "See [docs](guide.md) for details."
+        shadow = strip_code_spans(md)
+        self.assertIn("[docs](guide.md)", shadow)
+
+
+class TestLinkRE(unittest.TestCase):
+    def test_plain_link(self):
+        m = LINK_RE.search("[text](target.md)")
+        self.assertIsNotNone(m)
+        self.assertEqual(m.group(2), "target.md")
+
+    def test_link_with_title(self):
+        m = LINK_RE.search('[text](target.md "My Title")')
+        self.assertIsNotNone(m)
+        self.assertEqual(m.group(2), "target.md")
+
+    def test_link_with_fragment(self):
+        m = LINK_RE.search("[text](doc.md#section)")
+        self.assertIsNotNone(m)
+        self.assertEqual(m.group(2), "doc.md#section")
+
+    def test_no_match_on_image(self):
+        # Image links (![...](url)) contain the same syntax — LINK_RE will match
+        # the inner part; they should be treated as pass-through by callers.
+        m = LINK_RE.search("![alt](image.png)")
+        # The regex matches the inner ](url) portion — callers must handle images.
+        self.assertIsNotNone(m)
+
+
+class TestMachinePathRE(unittest.TestCase):
+    def test_file_uri(self):
+        self.assertTrue(MACHINE_PATH_RE.search("file:///Users/alice/project"))
+
+    def test_macos_path(self):
+        self.assertTrue(MACHINE_PATH_RE.search("/Users/alice/project"))
+
+    def test_linux_path(self):
+        self.assertTrue(MACHINE_PATH_RE.search("/home/alice/project"))
+
+    def test_windows_path_single_backslash(self):
+        self.assertTrue(MACHINE_PATH_RE.search("C:\\Users\\alice"))
+
+    def test_github_url_not_flagged(self):
+        self.assertFalse(
+            MACHINE_PATH_RE.search("https://github.com/danielvm-git/bigpowers")
+        )
+
+
+class TestRewriteLinksForPi(unittest.TestCase):
+    """Tests run without a real repo tree — path existence is irrelevant here;
+    we only verify that the URL construction logic is correct."""
+
+    NAME = "my-skill"
+
+    def _rw(self, body):
+        return rewrite_links_for_pi(body, self.NAME)
+
+    def test_external_link_untouched(self):
+        body = "[docs](https://example.com)"
+        self.assertEqual(self._rw(body), body)
+
+    def test_anchor_only_untouched(self):
+        body = "[section](#heading)"
+        self.assertEqual(self._rw(body), body)
+
+    def test_absolute_path_untouched(self):
+        body = "[root](/absolute/path.md)"
+        self.assertEqual(self._rw(body), body)
+
+    def test_relative_link_repointed(self):
+        body = "[ref](REFERENCE.md)"
+        result = self._rw(body)
+        # Must not contain the original bare target
+        self.assertNotIn("](REFERENCE.md)", result)
+        # Must be a relative path targeting the skills source tree
+        self.assertIn("REFERENCE.md", result)
+
+    def test_fragment_preserved(self):
+        body = "[section](REFERENCE.md#anchor)"
+        result = self._rw(body)
+        self.assertIn("#anchor", result)
+        # Fragment must not be mangled into a path component
+        self.assertNotIn("anchor" + os.sep, result)
+
+    def test_link_with_title_attribute(self):
+        body = '[ref](REFERENCE.md "My Title")'
+        result = self._rw(body)
+        # Must not be left unrewritten
+        self.assertNotIn("](REFERENCE.md", result)
+
+    def test_code_block_links_not_rewritten(self):
+        body = "Real: [ref](REFERENCE.md)\n\n```\n[fake](nowhere.md)\n```\n"
+        result = self._rw(body)
+        # The real link should be rewritten
+        self.assertNotIn("](REFERENCE.md)", result)
+        # The code-block link must be untouched
+        self.assertIn("[fake](nowhere.md)", result)
+
+    def test_inline_code_link_not_rewritten(self):
+        body = "Example: `[x](bad.md)` — real [ref](REFERENCE.md)."
+        result = self._rw(body)
+        self.assertIn("[x](bad.md)", result)  # inline code preserved
+        self.assertNotIn("](REFERENCE.md)", result)  # real link rewritten
+
+
+if __name__ == "__main__":
+    unittest.main()