/brain-link-discipline

name: brain-link-discipline
version: 1.0.0
description: |
  When you report a brain page to the user — created, edited, committed, or
  relayed from a subagent — a working link is part of the deliverable, in the
  SAME message. Derive the path mechanically (git ls-files --full-name), push
  BEFORE linking, verify the link resolves when a hosted remote exists, and
  degrade through a defined fallback chain when it doesn't. Inside brain
  pages the rule inverts: relative links preserve the link graph; absolute
  URLs are for chat deliverables only.
triggers:
  - "give me the link"
  - "where is the page"
  - "why does this link 404"
  - "brain link discipline"
  - "rewrite subagent paths"
  - "report the pages you created"
  - "send me a clickable link"
  - "link the page in the same message"
mutating: true
writes_pages: false
upstream: brain-link-on-commit@fc834ee + brain-link-report@fc834ee
# brain_first: exempt — this skill governs outbound-message link formatting
# and performs no entity/fact lookups. Its only network call is an HTTP
# existence check against the user's own hosted git remote (link
# verification, not data retrieval). Declarative opt-out.
brain_first: exempt

brain-link-discipline — The Link Is Part of the Deliverable

> **Convention:** see [_output-rules.md](../_output-rules.md) — the > Deterministic Links section carries the cross-skill canon (in-page relative > vs in-message verified, plus the fallback chain). This skill carries the > mechanics: path derivation, push-before-link ordering, verification, the > subagent-relay rewrite, and bulk-list formatting. > > **Convention:** [conventions/brain-first.md](../conventions/brain-first.md) > states the one-line principle ("every brain page reference in output should > use a clickable link format appropriate to the deployment"). This skill is > that line's full expansion.

This is a reporting convention the harness routes brain-page delivery messages through — a standing rule to apply when composing such messages, not a mechanical guarantee enforced by tooling.

The rule (same message)

If you commit and push a brain page, the link goes in the SAME message that reports the work. Every time. No "let me commit and push" without the link landing in that same reply once the push succeeds. The user should never have to ask "give me the link" or "where is the page."

This applies to:

• Any message reporting a created or edited brain page
• Bulk reports ("5 pages created" — every page gets its own link line)
• Referencing a brain page in normal conversation
• Relaying subagent results that mention brain paths (rewrite first — see below)

The most common link bug is committing a brain page and forcing the user to go find it. The link is a deliverable, not a follow-up.

Scope split: in-message vs in-page (the inversion)

The two output surfaces take OPPOSITE link forms:

| Surface | Link form | Why | |---|---|---| | Chat message to the user | Absolute, verified URL (or the fallback chain below) | Repo-relative paths aren't clickable in chat surfaces | | Inside a brain page body | RELATIVE markdown link: `[Alice Example](../people/alice-example.md)` | gbrain's link extraction builds the links/backlinks graph — which powers relational retrieval — from filesystem-relative links. An absolute URL between two brain pages is invisible to that graph |

**Never write absolute URLs for page-to-page references inside a brain page.** Absolute URLs in a page body are for genuinely external targets only. Frontmatter `related:` / `people:` keys stay bare relative paths (machine-parsed, not rendered prose). After a link-heavy write, `gbrain check-backlinks check` audits the graph and `gbrain sync --no-pull` makes the pages searchable.

Deriving the path mechanically

The repo-relative path a hosted git remote serves is relative to the **git repo root** (`git rev-parse --show-toplevel`), NOT your current working directory. When the repo root sits above your working directory, hand- stripping your cwd prefix silently drops the intermediate directory segment and every link you build 404s. Never hand-strip a prefix. Derive:

# From anywhere inside the repo, prints the EXACT path the remote serves:
cd "$(dirname <file>)" && git ls-files --full-name "$(basename <file>)"
# e.g. people/alice-example.md

Then assemble:

https://<host>/<owner>/<repo>/blob/<branch>/<that-exact-path>

• `<host>/<owner>/<repo>` from `git remote get-url origin`
• `<branch>` from `git rev-parse --abbrev-ref HEAD` (or the remote's default branch)
• `/blob/` for files, `/tree/` for directories (GitHub-style hosts)

Sequence (push BEFORE link)

1. Write/edit the brain file. 2. `scripts/brain-commit-push.sh "<msg>" <file>` (or `gbrain git commit-push -m "<msg>" -- <file>` when the brain has no helper). It commits only that file under the checkout's writer lock and pushes, merging remote commits without touching other agents' files. 3. **Verify the push landed** — the command must exit 0 and print `pushed <sha> to origin/<branch>` (or `nothing to commit`; a `[gbrain notice]` that the checkout lags is still a landed push). A hosted URL 404s until the push completes. On a non-zero exit, output no link: retry once on `commit_lock_busy`; stop and tell the user on `integrate_conflict` or `writer_coordinator_required`; never fall back to stash, `pull --rebase` or a plain push ([outcomes](https://github.com/garrytan/gbrain/blob/master/docs/guides/shared-checkout-git.md#outcomes)). 4. **In the SAME message that reports the commit, output the link** — as a clickable markdown link or bare URL, never a backticked code span.

Verify before linking (when a hosted remote exists)

Before including a hosted-remote link in a user-facing message, confirm the path exists on the remote. GitHub example (private repos need a token):

curl -sf -o /dev/null -w '%{http_code}' \
  -H "Authorization: token $GITHUB_TOKEN" \