docs(makefile): document develop/master publish workflow

Makefile

@@ -1,8 +1,37 @@
-# DuckBrain development harness (branch-only tooling; never published to master).
+# DuckBrain development harness — Makefile
 #
-# Workflow:
-#   make test     run the unit test suite (installs dev dependencies first if needed)
-#   make publish  sync develop -> master (human-only; git push origin master afterwards)
+# This file (along with tests/, phpunit.xml, composer.*, .gitignore) lives
+# ONLY on the develop branch. master is a publish-only vitrine that contains
+# nothing but the readable artifact: nobody commits to master directly, and
+# no file outside the WHITELIST below ever reaches it.
+#
+# Daily loop:
+#   make test     run the unit suite (sqlite :memory:, no containers, no
+#                 network; installs dev dependencies first if missing)
+#   ...then develop on develop and commit there as usual.
+#
+# Publishing ritual (human only — AI agents must never run it; it commits):
+#   1. make publish MSG="feat: ..."   (MSG optional, defaults to "sync: <date>")
+#   2. review the new master commit (git log -1 refs/heads/master); if the
+#      generated message needs polish, rewrite it BEFORE pushing, e.g.
+#      from Emacs
+#   3. git push origin master         (manual on purpose: pushing is a
+#                                      decision, never a side effect)
+#
+# How publish builds master — wipe-and-rebuild mirror, no merges, no
+# cherry-picks (see design decisions behind establish-dev-publish-workflow):
+#   - refuses to run off develop or with a dirty working tree
+#   - checks master out into a disposable worktree under .publish/
+#     (your current working tree is never touched)
+#   - for each WHITELIST path: removes master's copy and checks out develop's,
+#     so deleted/renamed artifact files never survive as ghosts in master
+#   - BLACKLIST then subtracts noise found INSIDE whitelisted paths
+#   - creates the commit only when the artifact actually changed; its body
+#     lists the develop commits (after the last-sync tag) that touched
+#     WHITELIST paths — pure-noise commits are filtered out automatically
+#   - moves the last-sync tag to develop's tip, removes the worktree, and
+#     prints any root entry left out of WHITELIST (add it if it belongs to
+#     the artifact)
 
 SHELL := /bin/bash