+#
+# Policy hook script is invoked like this:
+# POLICY-HOOK-SCRIPT DISTRO DGIT-REPOS-DIR DGIT-LIVE-DIR DISTRO-DIR ACTION...
+# ie.
+# POLICY-HOOK-SCRIPT ... check-list [...]
+# POLICY-HOOK-SCRIPT ... check-package PACKAGE [...]
+# POLICY-HOOK-SCRIPT ... push PACKAGE \
+# VERSION SUITE TAGNAME DELIBERATELIES [...]
+# POLICY-HOOK-SCRIPT ... push-confirm PACKAGE \
+# VERSION SUITE TAGNAME DELIBERATELIES FRESH-REPO|'' [...]
+#
+# Exit status is a bitmask. Bit weight constants are defined in Dgit.pm.
+# NOFFCHECK (2)
+# suppress dgit-repos-server's fast-forward check ("push" only)
+# FRESHREPO (4)
+# blow away repo right away (ie, as if before push or fetch)
+# ("check-package" and "push" only)
+# any unexpected bits mean failure, and then known set bits are ignored
+# if no unexpected bits set, operation continues (subject to meaning
+# of any expected bits set). So, eg, exit 0 means "continue normally"
+# and would be appropriate for an unknown action.
+#
+# cwd for push and push-confirm is a temporary repo where the
+# to-be-pushed objects have been received; TAGNAME is the
+# version-based tag
+#
+# FRESH-REPO is '' iff the repo for this package already existed, or
+# the pathname of the newly-created repo which will be renamed into
+# place if everything goes well. (NB that this is generally not the
+# same repo as the cwd, because the objects are first received into a
+# temporary repo so they can be examined.)
+#
+# if push requested FRESHREPO, push-confirm happens in said fresh repo
+# and FRESH-REPO is guaranteed not to be ''.
+#
+# policy hook for a particular package will be invoked only once at
+# a time - (see comments about DGIT-REPOS-DIR, above)
+#
+# check-list and check-package are invoked via the --cron option.
+# First, without any locking, check-list is called. It should produce
+# a list of package names (one per line). Then check-package will be
+# invoked for each named package, in each case after taking an
+# appropriate lock.
+#
+# If policy hook wants to run dgit (or something else in the dgit
+# package), it should use DGIT-LIVE-DIR/dgit (etc.)
+