devallibus · HorchataHTML · Aug 4, 2026
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
 {
   "name": "shiplog",
   "description": "Git-as-knowledge-graph workflow for traceability across issues, branches, commits, reviews, and PRs.",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "author": {
     "name": "devallibus"
   },

diff --git a/.github/workflows/cross-ref-check.yml b/.github/workflows/cross-ref-check.yml
@@ -0,0 +1,34 @@
+# Rejects legacy cross-reference forms that the audit found drifting:
+# bare `shiplog:<skill>` references outside HTML envelopes. Shiplog's own
+# units are referenced by file path; the `plugin:skill` syntax is reserved
+# for external plugins (e.g. `ork:commit`, `superpowers:brainstorming`).
+#
+# Implementation: pure shell + grep, no third-party action. Runs on PRs only.
+
+name: Cross-reference check
+
+on:
+  pull_request:
+    # List both master and main so a future default-branch rename does
+    # not silently no-op the check. GitHub Actions does not template
+    # `branches:`, so a literal list is the simplest correct shape.
+    branches: [master, main]
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout PR
+        uses: actions/checkout@v4
+
+      - name: Reject legacy shiplog:skill refs outside envelopes
+        shell: bash
+        run: |
+          set -euo pipefail
+          # '<!-- shiplog:' opens an envelope; any bare shiplog:<skill> is legacy.
+          if grep -rnE '(^|[^!:-])shiplog:[a-z]+' skills commands --include='*.md' \
+             | grep -vE '<!-- shiplog:'; then
+            echo "::error::Legacy 'shiplog:<skill>' reference found. Use a file path instead."
+            exit 1
+          fi
+          echo "OK: no legacy shiplog:<skill> references."
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -47,7 +47,7 @@ Key contributor expectations:
 
 - Branch from your `<default-branch>` as `issue/<id>-<slug>`.
 - Commit subjects use `<type>(#<id>): <msg>` or `<type>(#<id>/<Tn>): <msg>` for task-scoped commits.
-- PR body follows the template in [`skills/shiplog/pr.md`](skills/shiplog/pr.md): envelope, summary, journey timeline, changes, verification, knowledge for future reference.
+- PR body follows the template in [`skills/shiplog/pr.md`](skills/shiplog/pr.md): envelope, summary, journey timeline, changes, verification, knowledge for future reference. (The runnable PR policy lives in `commands/shiplog/pr.md`; the template alone is here.)
 - Sign every shiplog artifact (PR body, signed comments, review comments) with `<role>: <family>/<version> (<tool>)`.
 - Cross-model review is required before merge. See [`skills/shiplog/references/closure-and-review.md`](skills/shiplog/references/closure-and-review.md) §3.
 

diff --git a/commands/shiplog/pr.md b/commands/shiplog/pr.md
@@ -21,7 +21,7 @@ Push the branch and create a PR whose body is a complete timeline of the work: i
 Authored-by: <family>/<version> (<tool>)
 Last-code-by: <family>/<version> (<tool>)
 ```
-`Last-code-by:` is updated whenever new code is pushed to the branch after PR creation. See SKILL.md §8 for code provenance rules.
+`Last-code-by:` is updated whenever new code is pushed to the branch after PR creation. See SKILL.md → "Agent Identity Signing" for code provenance rules.
 
 **Review gate:** do NOT merge until a cross-model `Reviewed-by:` + `Disposition: approve` (or `approve-with-follow-ups`) comment exists on the PR. Self-review does not satisfy the gate. See `commands/shiplog/review.md` for the full review sub-skill, and `references/closure-and-review.md` §3 for the cross-model gate policy.
 

diff --git a/skills/shiplog/SKILL.md b/skills/shiplog/SKILL.md
@@ -17,7 +17,7 @@ Use GitHub as a complete knowledge graph where every brainstorm, commit, review,
 
 ## Golden-Path Walkthrough
 
-A complete issue-to-merge example using a concrete fake issue `#999`. Follow this sequence and every artifact produced will pass the acceptance checklists in `commands/shiplog/*.md`.
+A complete issue-to-merge example using a concrete fake issue `#999`. Follow this sequence and every artifact produced will pass the acceptance checklists in `commands/shiplog/*.md`. The blocks here are illustrative; the canonical, copy-ready templates live in the phase sub-skills under `skills/shiplog/` (see the Phase Sub-skill Index) and in `references/`. If a template changes, verify this walkthrough example is updated to match.
 
 ### Step 1 — Plan Capture (`/shiplog plan`)
 
@@ -190,10 +190,17 @@ Cross-model gate is satisfied (`Last-code-by: claude/sonnet-4.6` ≠ `Reviewed-b
 
 ## Verb Grid
 
-Each `/shiplog <phase>` slash command maps to one sub-skill file. Load the file for that phase — it owns policy, templates, and acceptance checklist.
+Each `/shiplog <command>` slash command maps to one command file under `commands/shiplog/`. Load the command file — it owns the phase's runnable policy, templates, and acceptance checklist.
 
-| Command | What it does | Sub-skill |
-|---------|-------------|-----------|
+Two trees co-exist and complement each other:
+
+- `commands/shiplog/*.md` — the slash commands (`plan`, `start`, `hunt`, `commit`, `pr`, `review`, `lookup`, `resume`, `models`). Executable policy: runnable queries, allowed tools, acceptance checklists.
+- `skills/shiplog/*.md` — the phase sub-skills (`brainstorm`, `branch`, `discovery`, `commit`, `pr`, `lookup`, `timeline`). Template library + routing annotations; referenced by phase, not invoked as commands.
+
+The phase sub-skills are indexed below in "Phase Sub-skill Index". Open a phase sub-skill when you need its template or checklist; open the matching command file when you are about to execute that phase.
+
+| Command | What it does | Command file |
+|---------|-------------|--------------|
 | `/shiplog plan` | Capture a brainstorm as a GitHub planning issue with envelope + task contracts | `commands/shiplog/plan.md` |
 | `/shiplog start` | Create a branch from an issue, swap lifecycle labels, post session-start comment | `commands/shiplog/start.md` |
 | `/shiplog hunt` | Triage open issues and PRs; rank by readiness; detect gate-satisfying reviews | `commands/shiplog/hunt.md` |
@@ -207,6 +214,24 @@ Each `/shiplog <phase>` slash command maps to one sub-skill file. Load the file
 
 ---
 
+## Phase Sub-skill Index
+
+The phase sub-skills under `skills/shiplog/` carry templates, routing annotations, and acceptance checklists per phase. They are keyed the same way the command files are keyed, but are loaded by phase (look up the template you need), not invoked as slash commands.
+
+| Phase | Sub-skill | Holds templates for |
+|-------|-----------|---------------------|
+| 1. Brainstorm   | `skills/shiplog/brainstorm.md` | Issue creation, task contracts, plan envelope |
+| 2. Branch Setup | `skills/shiplog/branch.md`     | Session-start comment, delegation handoffs |
+| 3. Discovery    | `skills/shiplog/discovery.md`  | Discovery issues, blocker cross-reference comments, stacked-PR flow |
+| 4. Commit       | `skills/shiplog/commit.md`     | Commit-context comments |
+| 5. PR           | `skills/shiplog/pr.md`         | PR timeline body (full + partial delivery) |
+| 6. Lookup       | `skills/shiplog/lookup.md`     | Retrieval results, triage-scan output formats |
+| 7. Timeline     | `skills/shiplog/timeline.md`   | Session-start/resume, milestone, blocker, closure artifacts |
+
+**Single source of truth:** `references/phase-templates.md` is a compatibility pointer that indexes the same files; keep this index and that pointer in sync. See `references/closure-and-review.md` for the review sign-off template (owned there, cross-referenced from `skills/shiplog/pr.md`).
+
+---
+
 ## Canonical Kind → Tag → Label Map
 
 `kind:` in envelope YAML is the source of truth. Title tags (`[shiplog/<tag>]`) and GitHub labels (`shiplog/<label>`) are derived views on `kind:`. When a new artifact kind is defined, it is added here once and all three surfaces are updated together.
@@ -468,7 +493,7 @@ The timeline comment is the minimum: one paragraph explaining what happened, why
 ## Edge Cases
 
 - **No issue exists:** Let the user work. At first commit or PR, offer to create a tracking issue.
-- **Mid-work activation:** Check branch name for `issue/N-*`. If found, add catch-up timeline comment via `shiplog:timeline`. If not, offer retroactive issue creation.
+- **Mid-work activation:** Check branch name for `issue/N-*`. If found, add catch-up timeline comment via `skills/shiplog/timeline.md`. If not, offer retroactive issue creation.
 - **Small tasks (< 30 min):** Lightweight protocol - issue optional, branch still created, PR sections can be brief.
 - **Hotfix / emergency:** Fix first. Create issue and PR after, backfilling the timeline.
 - **Post-merge cleanup:** Remove a worktree only when its branch is merged, no open PR still depends on it, and it is not the active workspace. See `references/orchestrator-protocol.md`.
@@ -504,12 +529,14 @@ Key rules:
 
 ### Integration Map
 
-This skill ORCHESTRATES. Sub-skills under `commands/shiplog/` each own their phase's policy, runnable queries, and acceptance checklist in a single file — no cross-file navigation required during execution. References in `references/` are deep-dive anchors for cross-cutting policy only.
+This skill ORCHESTRATES. Command files under `commands/shiplog/` each own their phase's policy, runnable queries, and acceptance checklist in a single file — no cross-file navigation required during execution. References in `references/` are deep-dive anchors for cross-cutting policy only.
+
+Alongside the command files, `skills/shiplog/*.md` are the phase sub-skills carrying templates and routing annotations (open them by phase — see "Phase Sub-skill Index"). The command file is the executable entry point for a phase; the phase sub-skill is its template/checklist companion. Where both exist under the same name (`commit`, `pr`, `lookup`), they are distinct: `commands/` = runnable policy, `skills/` = template library.
 
-#### Sub-skill map
+#### Command map
 
-| Phase | Sub-skill | Owns |
-|-------|-----------|------|
+| Phase | Command file | Owns |
+|-------|--------------|------|
 | Plan Capture | `commands/shiplog/plan.md` | Brainstorm-to-issue policy, gh issue create template, envelope requirements |
 | Branch Setup | `commands/shiplog/start.md` | Branch naming, label swap, session-start comment template |
 | Triage / Hunt | `commands/shiplog/hunt.md` | PR+issue triage, signed-review detection (comment-based), reviewability classification |
@@ -527,7 +554,8 @@ This skill ORCHESTRATES. Sub-skills under `commands/shiplog/` each own their pha
 | Merge conditions | `references/closure-and-review.md` §5 | Gate satisfaction conditions; risk-based requirements |
 | Closure evidence | `references/closure-and-review.md` §1–2 | Evidence requirements; closure comment format |
 | Envelope schema | `references/artifact-envelopes.md` §1 | Triage field derivation rule; field definitions |
-| Signing spec | `SKILL.md §8` | Authored-by / Updated-by / Reviewed-by / Last-code-by rules |
+| Signing spec | `SKILL.md → "Agent Identity Signing"` | Authored-by / Updated-by / Reviewed-by / Last-code-by rules |
+| Worktree cleanup | `references/orchestrator-protocol.md` | Canonical portable cleanup sequence (`skills/shiplog/branch.md` duplicates this block) |
 
 #### External skill delegation
 

diff --git a/skills/shiplog/brainstorm.md b/skills/shiplog/brainstorm.md
@@ -6,13 +6,13 @@ description: "Phase 1: Capture brainstorming output as a GitHub issue with struc
 # Plan Capture (Phase 1)
 
 <!-- routing: tier-1, plan -->
-<!-- cross-cutting: references/model-routing.md (Step 0), SKILL.md §8 (Agent Identity Signing), references/labels.md -->
+<!-- cross-cutting: references/model-routing.md (Step 0), SKILL.md → "Agent Identity Signing", references/labels.md -->
 
 0. **Routing check.** Run the phase entry check from `references/model-routing.md`. On first activation, if `.shiplog/routing.md` is missing, run the setup prompt first.
 
 1. **Run the brainstorm.** Follow `references/brainstorm-workflow.md` for the design exploration process. External skills (`superpowers:brainstorming`, `ork:brainstorming`) may be used for the exploration phase (steps 1-4) but output capture (steps 5-6) follows the internalized workflow.
 
-2. **Capture as GitHub Issue (Full Mode).** Before the first labeled create in a repo, bootstrap the Shiplog labels per `references/labels.md`. Create the issue with `shiplog/plan` already applied using the template below. Sign the issue body per the signing spec — see SKILL.md §8 (Agent Identity Signing).
+2. **Capture as GitHub Issue (Full Mode).** Before the first labeled create in a repo, bootstrap the Shiplog labels per `references/labels.md`. Create the issue with `shiplog/plan` already applied using the template below. Sign the issue body per the signing spec — see SKILL.md → "Agent Identity Signing".
 
    Before writing the final issue body, classify factual claims:
    - **Internal claims** about this repository's code, tests, configuration, or committed docs can be verified from the repo itself.
@@ -21,7 +21,7 @@ description: "Phase 1: Capture brainstorming output as a GitHub issue with struc
 
 3. **Store in knowledge graph.** If `ork:remember` is available, store the key decision.
 
-4. **Transition.** Proceed to `shiplog:branch` if the user wants to start work.
+4. **Transition.** Proceed to `skills/shiplog/branch.md` if the user wants to start work.
 
 ---
 

diff --git a/skills/shiplog/branch.md b/skills/shiplog/branch.md
@@ -6,7 +6,7 @@ description: "Phase 2: Create a branch from an issue, set up worktree, and post
 # Branch Setup (Phase 2)
 
 <!-- routing: tier-2, plan then agent -->
-<!-- cross-cutting: references/model-routing.md (Step 0), SKILL.md §8 (Agent Identity Signing), references/labels.md, references/shell-portability.md, references/orchestrator-protocol.md -->
+<!-- cross-cutting: references/model-routing.md (Step 0), SKILL.md → "Agent Identity Signing", references/labels.md, references/shell-portability.md, references/orchestrator-protocol.md -->
 
 0. **Routing check.** Run the phase entry check from `references/model-routing.md`.
 
@@ -33,7 +33,7 @@ description: "Phase 2: Create a branch from an issue, set up worktree, and post
    If a delegated lane later uses a forked workspace, tmux session, or other runtime-specific isolation backend, keep this feature branch/worktree as the canonical shiplog record for the work.
    **Fallback (in-place checkout):** Only when the user explicitly requests no worktree.
 
-3. **Post timeline entry.** Comment on the issue using the session-start template below. Record the workspace path when known. Sign per the signing spec — see SKILL.md §8 (Agent Identity Signing).
+3. **Post timeline entry.** Comment on the issue using the session-start template below. Record the workspace path when known. Sign per the signing spec — see SKILL.md → "Agent Identity Signing".
 
 4. **Load plan** if it exists. Delegate to `superpowers:executing-plans` or `ork:implement`.
    For delegated or tier-3 work, the plan should define a contract: allowed files, forbidden changes, stop conditions, verification, return artifact, and decision budget.
@@ -159,6 +159,10 @@ Track the primary feature worktree from session start through cleanup.
 
 Portable cleanup sequence:
 
+> **Canonical source:** this same cleanup sequence is maintained in `references/orchestrator-protocol.md`
+> ("Cleanup commands"), which owns it. Keep both copies in sync when changing it, or replace this copy
+> with a pointer to the canonical block.
+
 ```bash
 git fetch origin
 git branch --merged origin/$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name')
@@ -180,6 +184,6 @@ git branch -d <branch-name>
 
 ## Edge Cases
 
-**Session resume:** Detect the issue from the current branch name or worktree. If the branch has an existing worktree, `cd` into it. Find linked PRs, read comments, add "Session resumed" timeline comment via `shiplog:timeline`.
+**Session resume:** Detect the issue from the current branch name or worktree. If the branch has an existing worktree, `cd` into it. Find linked PRs, read comments, add "Session resumed" timeline comment via `skills/shiplog/timeline.md`.
 
 **Post-merge cleanup:** If the branch is merged and no open PR still depends on it, run the cleanup protocol above or dispatch a dedicated cleanup lane per `references/orchestrator-protocol.md`.
diff --git a/skills/shiplog/commit.md b/skills/shiplog/commit.md
@@ -6,13 +6,13 @@ description: "Phase 4: Commit with conventional format and post context comments
 # Commit Context (Phase 4)
 
 <!-- routing: tier-3, agent -->
-<!-- cross-cutting: references/model-routing.md (Step 0), SKILL.md §8 (Agent Identity Signing), references/verification-profiles.md -->
+<!-- cross-cutting: references/model-routing.md (Step 0), SKILL.md → "Agent Identity Signing", references/verification-profiles.md -->
 
 0. **Routing check.** Run the phase entry check from `references/model-routing.md`.
 
 1. **Create the commit.** Follow `references/commit-workflow.md`. External commit skills may still be used for convenience, but the conventions in the internal workflow take precedence. Format: `<type>(#<issue-id>): <description>`. When a commit addresses a specific task, include the task ID: `<type>(#<issue-id>/<Tn>): <description>`.
 
-2. **Add context comment** for significant commits. Document the reasoning and verification on the issue. Sign per the signing spec — see SKILL.md §8 (Agent Identity Signing).
+2. **Add context comment** for significant commits. Document the reasoning and verification on the issue. Sign per the signing spec — see SKILL.md → "Agent Identity Signing".
 
 **When to add context comments:** After significant functionality, unexpected discoveries, approach changes, or tricky bug fixes. Not after trivial commits.
 

diff --git a/skills/shiplog/discovery.md b/skills/shiplog/discovery.md
@@ -6,7 +6,7 @@ description: "Phase 3: Handle mid-work discoveries — fix inline, stack a prere
 # Discovery Handling (Phase 3)
 
 <!-- routing: tier-2, plan then agent -->
-<!-- cross-cutting: references/model-routing.md (Step 0), SKILL.md §8 (Agent Identity Signing), references/labels.md, references/shell-portability.md -->
+<!-- cross-cutting: references/model-routing.md (Step 0), SKILL.md → "Agent Identity Signing", references/labels.md, references/shell-portability.md -->
 
 0. **Routing check.** Run the phase entry check from `references/model-routing.md`.
 
@@ -20,9 +20,9 @@ Discovery made during work
   +-- Refactoring opportunity?             -> Create issue tagged "refactor"
 ```
 
-**3a (stack a prerequisite):** Commit current progress. Create a new issue first (so the ID exists), then create the stacked branch. Label the new issue `shiplog/discovery` and `shiplog/stacked`. Cross-reference on the parent issue and add `shiplog/blocker` to the parent while it is blocked. Sign both artifacts per the signing spec — see SKILL.md §8 (Agent Identity Signing).
+**3a (stack a prerequisite):** Commit current progress. Create a new issue first (so the ID exists), then create the stacked branch. Label the new issue `shiplog/discovery` and `shiplog/stacked`. Cross-reference on the parent issue and add `shiplog/blocker` to the parent while it is blocked. Sign both artifacts per the signing spec — see SKILL.md → "Agent Identity Signing".
 
-**3b (independent discovery):** Create new issue (same template without "blocks parent") and label it `shiplog/discovery`. Add timeline comment. Continue current work. Sign per the signing spec — see SKILL.md §8 (Agent Identity Signing).
+**3b (independent discovery):** Create new issue (same template without "blocks parent") and label it `shiplog/discovery`. Add timeline comment. Continue current work. Sign per the signing spec — see SKILL.md → "Agent Identity Signing".
 
 ---