From 6a38b4443c9d9f42e734855a2ab99a2192c665e0 Mon Sep 17 00:00:00 2001
From: reachableceo <charles@turnsys.com>
Date: Thu, 3 Sep 2026 05:28:57 -0500
Subject: [PATCH] docs(agents): cross-linking house rule + mastodon post tool
 [#743][#441]
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Clickable-refs mandate from Charles: ticket comments link commits,
commit bodies link the Redmine comment URL, Discourse links both —
one click between Redmine/Gitea/Discourse (GLPI/CMDB change control
will extend this). Mechanical body-URL check queued under #441.
scripts/mastodon/post.sh: zero-install curl poster; creds land in
~/.creds/mastodon.env (MASTODON_URL/MASTODON_TOKEN, write scope).
---
 AGENTS.md                | 22 ++++++++++++++++++
 scripts/mastodon/post.sh | 49 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 71 insertions(+)
 create mode 100755 scripts/mastodon/post.sh

diff --git a/AGENTS.md b/AGENTS.md
index 806be5e..a0741c8 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -424,6 +424,28 @@ vendor/             Vendored KNELShellFramework
    justification. A script that emits any diagnostic is a protocol violation.
    Non-bash scripts (PHP with `.sh` shebang `#!/usr/bin/php`, etc.) are exempt.
 
+## Cross-linking (NON-NEGOTIABLE)
+
+**Every artifact cross-references its related artifacts with CLICKABLE
+links.** House rule (Charles, 2026-09-02, [#743]) — becomes hard
+requirement once GLPI/CMDB change control is online (ITIL/ITSM ramp):
+
+- Redmine ticket comments link the commits they describe (full Gitea URL,
+  e.g. `https://git.knownelement.com/KNEL/PFVCluster/commit/<sha>`).
+- Commit bodies carry the full URL of the corresponding Redmine comment
+  (`https://projects.knownelement.com/issues/NNN#note-M`) — the "meat"
+  lives in the comment; the commit body points at it.
+- Discourse posts link both the Redmine ticket and the Gitea repo/commit;
+  Redmine tickets and repo docs link their Discourse topics.
+- One click from ANY system reaches the other two. An artifact without its
+  links is not done.
+- When GLPI is online: change requests become the entry point for infra
+  changes and get cross-referenced into Redmine/Discourse/Gitea the same
+  way; CMDB items link their tickets and vice versa.
+
+Mechanical enforcement (rule-engine check for the ticket-comment URL in
+commit bodies when `[#NNN]` is present) is tracked under [#441].
+
 ## TDD & Linting
 
 - **Red/green TDD for all code.** Mandatory (founder 2026-08-27). Interim
diff --git a/scripts/mastodon/post.sh b/scripts/mastodon/post.sh
new file mode 100755
index 0000000..c155bd9
--- /dev/null
+++ b/scripts/mastodon/post.sh
@@ -0,0 +1,49 @@
+#!/usr/bin/bash
+#
+# post.sh — post a work-update status to Mastodon [#743]
+#
+# Zero-install: uses curl against the Mastodon REST API (host-hygiene
+# compliant — no packages on the host). Credentials come from the
+# centralized store:
+#   ~/.creds/mastodon.env   (MASTODON_URL, MASTODON_TOKEN)
+# Token needs write scope; create via Mastodon → Preferences → Development.
+#
+# Usage:
+#   post.sh [-v public|unlisted|private|direct] "status text (<=500 chars)"
+#
+set -euo pipefail
+
+CREDS="${HOME}/.creds/mastodon.env"
+if [ ! -r "$CREDS" ]; then
+  echo "post.sh: missing $CREDS (needs MASTODON_URL, MASTODON_TOKEN)" >&2
+  exit 2
+fi
+# shellcheck disable=SC1090
+. "$CREDS"
+if [ -z "${MASTODON_URL:-}" ] || [ -z "${MASTODON_TOKEN:-}" ]; then
+  echo "post.sh: MASTODON_URL / MASTODON_TOKEN not set in $CREDS" >&2
+  exit 2
+fi
+
+visibility="public"
+if [ "${1:-}" = "-v" ]; then
+  visibility="$2"
+  shift 2
+fi
+if [ $# -lt 1 ]; then
+  echo "usage: $0 [-v public|unlisted|private|direct] \"status text\"" >&2
+  exit 2
+fi
+
+status="$1"
+len=${#status}
+if [ "$len" -gt 500 ]; then
+  echo "post.sh: status too long ($len chars; hard ceiling 500)" >&2
+  exit 1
+fi
+
+curl -sS --max-time 30 -X POST "$MASTODON_URL/api/v1/statuses" \
+  -H "Authorization: Bearer $MASTODON_TOKEN" \
+  --data-urlencode "status=$status" \
+  --data-urlencode "visibility=$visibility" |
+  jq -r '"posted id=\(.id) url=\(.url) visibility=\(.visibility)"'