Brain Link Discipline

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

Convention: see _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 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:

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. git add <file> && git commit -m "..." && git push
3. Verify the push landed — the push output must show the ref update (e.g. abc123..def456 main -> main). A hosted URL 404s until the push completes.
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" \
  "https://api.github.com/repos/<owner>/<repo>/contents/<repo-relative-path>"

Only send the link on 200. If you just pushed and the host API is lagging, the push output proving the ref moved is sufficient evidence — but never invent or guess a URL.

Send the token only to its issuing host. The Authorization: token header above targets api.github.com because the remote is a github.com remote. Never send $GITHUB_TOKEN to a host you derived from git remote get-url origin without confirming it is the token's issuing host: a doctored or unexpected remote (origin pointed at an attacker's host, an enterprise/self-hosted host the token isn't scoped to) would harvest the credential. For a github.com remote, use api.github.com. For any other remote, verify UNAUTHENTICATED (a public-repo existence check needs no token) or skip verification and fall back to the ref-update evidence from the push. When in doubt, don't send the token.

Fallback chain (in order)

1. Hosted git-remote URL (verified). The brain repo has a remote on a host that renders files → build and verify as above.
2. Repo-relative path + scope note. No hosted remote (the default PGLite brain often has none, or the repo is local-only) → give the repo-relative path (people/alice-example.md) and say plainly that it's a local path in the brain repo.
3. gbrain publish output as an attachable HTML ARTIFACT. gbrain publish <page-path> emits a self-contained LOCAL HTML file (its output line is Published: <local-path>). Offer to attach or send that file — NEVER present it as a URL, because it isn't one. Use --password for sensitive content.

Subagent-relay rewrite rule

Subagents run in local context and return LOCAL paths. Relaying a subagent completion verbatim is the #1 source of link bugs: the subagent reports media/books/widget-co-notes.md (or an absolute path into the brain checkout) and the relay parrots it. Before converting a subagent completion into a user-facing reply, rewrite every brain-page path through the same derivation + fallback chain above.

When spawning subagents that will write brain pages, include in their task prompt:

Report brain pages as repo-relative paths from git ls-files --full-name. The parent rewrites them into links before relaying.