task-pipeline-skill 1.7.1 → 1.8.0

package/plugins/task-pipeline/skills/task-pipeline/templates/docgate.sh

@@ -18,12 +18,20 @@
 # PROGRESSIVE ARMING: a section whose input does not exist yet prints
 #   "dormant: … — no <artefact> yet" and does NOT fail. Dormant is visible so it is
 #   not forgotten, and green so a freshly seeded project does not start red.
+#
+# TWO REGISTER SHAPES, ONE CONTRACT: the project's decision home is either
+#   docs/DECISIONS.md (ids DEC-####) or docs/adr/NNNN-slug.md (ids ADR-NNNN). Every
+#   section below reads a NORMALISED INDEX built from whichever exists, so neither
+#   shape is a second-class citizen. Having both is itself an error: one home per
+#   project. Reading only one shape is how a fully populated ADR register sat behind
+#   eight green "dormant" lines while a planted violation went uncaught.
 
 set -u
 
 FAIL=0
 DOCS_DIR=${DOCS_DIR:-docs}
 DEC_FILE=${DEC_FILE:-$DOCS_DIR/DECISIONS.md}
+ADR_DIR=${ADR_DIR:-$DOCS_DIR/adr}
 OQ_FILE=${OQ_FILE:-$DOCS_DIR/OPEN_QUESTIONS.md}
 MAP_FILE=${MAP_FILE:-$DOCS_DIR/DOCMAP.md}
 RETRO_GLOB=${RETRO_GLOB:-$DOCS_DIR/superpowers}
@@ -40,12 +48,31 @@ ok()      { echo "ok:      $*"; }
 skipmsg() { echo "skip:    $*"; }
 dormant() { echo "dormant: $*"; }
 
-# Strip fenced code blocks: sample content is not a claim about this repository.
+# Strip what a reader never sees: fenced code blocks AND html comments. Sample
+# content is not a claim about this repository. The comment half is not fussiness —
+# a status line carrying `<!-- or: Superseded by ADR-0012 -->` made an entry read as
+# retired and invented an undefined id, from one aside nobody renders.
 # awk, because sed -i is not portable and this must run identically everywhere.
-strip_fences() {
+strip_asides() {
   awk '
     /^[ \t]*(```|~~~)/ { infence = !infence; print ""; next }
-    { if (infence) print ""; else print }
+    infence { print ""; next }
+    {
+      line = $0
+      # A comment carried over from an earlier line.
+      if (incomment) {
+        if (match(line, /-->/)) { line = substr(line, RSTART + RLENGTH); incomment = 0 }
+        else { print ""; next }
+      }
+      # Comments that open and close on this line.
+      while (match(line, /<!--.*-->/)) sub(/<!--.*-->/, "", line)
+      # An opener with no closer: KEEP THE PREFIX. Dropping the whole line threw
+      # away the "- **Status:** Accepted" that preceded the comment, and the entry
+      # then had no status at all — the id vanished from the index and every
+      # document citing it was reported as citing something undefined.
+      if (match(line, /<!--/)) { line = substr(line, 1, RSTART - 1); incomment = 1 }
+      print line
+    }
   ' "$1"
 }
 
@@ -63,17 +90,82 @@ fi
 while IFS= read -r f; do
   [ -f "$f" ] || continue
   flat=$(echo "$f" | tr '/' '_')
-  strip_fences "$f" > "$TMP/s_$flat"
+  strip_asides "$f" > "$TMP/s_$flat"
 done < "$TMP/files"
 
 flat_of() { echo "$TMP/s_$(echo "$1" | tr '/' '_')"; }
 
+# ---------- 0. the decision home — exactly one, and which shape ----------
+# entries: ID <TAB> FILE <TAB> STATUS-LINE      edges: SRC <TAB> MARKER <TAB> TARGET
+# conseq:  ID <TAB> DOC
+: > "$TMP/entries"; : > "$TMP/edges"; : > "$TMP/conseq"
+SHAPE="none"; ID_PREFIX=""
+
+have_reg=0; [ -f "$DEC_FILE" ] && have_reg=1
+have_adr=0
+if [ -d "$ADR_DIR" ]; then
+  find "$ADR_DIR" -type f -name '[0-9][0-9][0-9][0-9]-*.md' 2>/dev/null | sort > "$TMP/adrfiles"
+  [ -s "$TMP/adrfiles" ] && have_adr=1
+fi
+
+if [ "$have_reg" = "1" ] && [ "$have_adr" = "1" ]; then
+  err "two decision homes: $DEC_FILE and $ADR_DIR both hold entries — one project, one register (references/documentation.md)"
+fi
+
+# Pull the six owed fields out of one entry body on stdin, for id $1 in file $2.
+harvest_entry() {  # id file  (body on stdin)
+  _id=$1; _file=$2
+  while IFS= read -r line; do
+    case "$line" in
+      *'Status:'*)
+        grep -q "^$_id	" "$TMP/entries" 2>/dev/null || \
+          printf '%s\t%s\t%s\n' "$_id" "$_file" "$line" >> "$TMP/entries" ;;
+      *'Consequences / affects:'*)
+        echo "$line" | grep -o '`[^`]*`' | tr -d '`' | while IFS= read -r doc; do
+          case "$doc" in *.md) printf '%s\t%s\n' "$_id" "$doc" >> "$TMP/conseq" ;; esac
+        done ;;
+      *'Supersedes:'*|*'Contradicts:'*|*'Refines:'*)
+        _mk=$(echo "$line" | grep -o 'Supersedes\|Contradicts\|Refines' | head -1)
+        echo "$line" | grep -o '\(DEC\|ADR\)-[0-9][0-9]*' | while IFS= read -r tgt; do
+          [ "$tgt" = "$_id" ] || printf '%s\t%s\t%s\n' "$_id" "$_mk" "$tgt" >> "$TMP/edges"
+        done ;;
+    esac
+  done
+}
+
+if [ "$have_reg" = "1" ]; then
+  SHAPE="register"; ID_PREFIX="DEC"
+  # Split the fence-stripped register into one body per "### DEC-####" heading.
+  awk -v out="$TMP" '
+    /^### DEC-[0-9]+/ { id=$2; sub(/[^A-Za-z0-9-].*/,"",id); n++; f=out "/e_" n; ids[n]=id }
+    n { print > f }
+    END { for (i=1;i<=n;i++) print ids[i] > (out "/e_ids") }
+  ' "$(flat_of "$DEC_FILE")"
+  if [ -f "$TMP/e_ids" ]; then
+    _n=0
+    while IFS= read -r _id; do
+      _n=$((_n + 1))
+      harvest_entry "$_id" "$DEC_FILE" < "$TMP/e_$_n"
+    done < "$TMP/e_ids"
+  fi
+elif [ "$have_adr" = "1" ]; then
+  SHAPE="adr"; ID_PREFIX="ADR"
+  while IFS= read -r af; do
+    _num=$(basename "$af" | sed 's/^\([0-9][0-9]*\)-.*/\1/')
+    harvest_entry "ADR-$_num" "$af" < "$(flat_of "$af")"
+  done < "$TMP/adrfiles"
+fi
+
+DECS=$(wc -l < "$TMP/entries" | tr -d ' ')
+case "$SHAPE" in
+  none) dormant "decision home — neither $DEC_FILE nor $ADR_DIR/NNNN-*.md yet" ;;
+  *)    ok "decision home: $SHAPE ($DECS entr$([ "$DECS" = "1" ] && echo y || echo ies), ids $ID_PREFIX-####)" ;;
+esac
+
 # ---------- 1. relative links resolve ----------
-_bad=0
 while IFS= read -r f; do
   [ -f "$f" ] || continue
   dir=$(dirname "$f")
-  # grep -o on the link target; keep the line number for the message.
   grep -n -o '](\([^) ]*\))' "$(flat_of "$f")" 2>/dev/null |
   sed 's/](\(.*\))/\1/' |
   while IFS=: read -r ln target; do
@@ -82,28 +174,22 @@ while IFS= read -r f; do
     esac
     base=${target%%#*}
     [ -n "$base" ] || continue
-    if [ ! -e "$dir/$base" ]; then
-      echo "$f:$ln: dangling link -> $target" >> "$TMP/badlinks"
-    fi
+    [ -e "$dir/$base" ] || echo "$f:$ln: dangling link -> $target" >> "$TMP/badlinks"
   done
 done < "$TMP/files"
 if [ -s "$TMP/badlinks" ] 2>/dev/null; then
-  _bad=$(wc -l < "$TMP/badlinks" | tr -d ' ')
-  err "$_bad dangling relative link(s):"; sed 's/^/         /' "$TMP/badlinks"
+  err "$(wc -l < "$TMP/badlinks" | tr -d ' ') dangling relative link(s):"
+  sed 's/^/         /' "$TMP/badlinks"
 else
   ok "relative links resolve ($FILE_COUNT files)"
 fi
 
 # ---------- 2. every id referenced is defined ----------
-if [ ! -f "$DEC_FILE" ]; then
-  dormant "id integrity — no $DEC_FILE yet"
-  DECS=0; OQS=0
+if [ "$SHAPE" = "none" ]; then
+  dormant "id integrity — no decision home yet"
+  OQS=0
 else
-  # Read the FENCE-STRIPPED copy: a heading inside a ``` block is sample content,
-  # not a definition. Reading the raw file here counts the format example as an
-  # entry, and then "Next free ID" is wrong against a decision that never existed.
-  grep -o '^### DEC-[0-9][0-9]*' "$(flat_of "$DEC_FILE")" | sed 's/^### //' | sort -u > "$TMP/dec_def"
-  DECS=$(wc -l < "$TMP/dec_def" | tr -d ' ')
+  cut -f1 "$TMP/entries" | sort -u > "$TMP/dec_def"
   : > "$TMP/oq_def"
   [ -f "$OQ_FILE" ] && grep -o '^| *OQ-[0-9][0-9]*' "$(flat_of "$OQ_FILE")" | sed 's/^| *//' | sort -u > "$TMP/oq_def"
   OQS=$(wc -l < "$TMP/oq_def" | tr -d ' ')
@@ -113,7 +199,7 @@ else
   while IFS= read -r f; do
     [ -f "$f" ] || continue
     grep -v 'Next free ID' "$(flat_of "$f")" 2>/dev/null |
-      grep -o '\(DEC\|OQ\)-[0-9][0-9]*' | sed "s|^|$f |" >> "$TMP/refs"
+      grep -o "\($ID_PREFIX\|OQ\)-[0-9][0-9]*" | sed "s|^|$f |" >> "$TMP/refs"
   done < "$TMP/files"
 
   : > "$TMP/undef"
@@ -127,7 +213,10 @@ else
   fi
 fi
 
-# ---------- 3. "Next free ID" == max defined + 1 ----------
+# ---------- 3. the id allocator is sound ----------
+# Register shape: a stated "Next free ID" must equal max defined + 1.
+# ADR shape: there is no such line — the filename IS the allocator, so the sound
+# check is that no two files claim one number.
 check_next_free() {
   _file=$1; _prefix=$2; _deffile=$3
   [ -f "$_file" ] || { dormant "next-free-$_prefix — no $_file yet"; return; }
@@ -141,27 +230,46 @@ check_next_free() {
   # an octal digit, the expansion errors, the `if` takes its else branch and the
   # check prints ok. It passed for every id ending 0-7 and was silent for 8 and 9.
   # Found by the probe; the check was wrong, not the probe.
+  _claim_raw=$_claim
   _claim=$(echo "$_claim" | sed 's/^0*//'); [ -n "$_claim" ] || _claim=0
   if [ ! -s "$_deffile" ]; then _max=0; else
     _max=$(sed "s/^$_prefix-//" "$_deffile" | sed 's/^0*//' | sort -n | tail -1)
     [ -n "${_max:-}" ] || _max=0
   fi
   _want=$((_max + 1))
-  if [ "$((_claim))" -ne "$_want" ]; then
+  if [ "$_claim" -ne "$_want" ]; then
     err "$_file: 'Next free ID' claims $_prefix-$_claim, highest defined is $_max (expected $_want)"
   else
-    ok "next free $_prefix id is correct ($_prefix-$_claim)"
+    ok "next free $_prefix id is correct ($_prefix-$_claim_raw)"
   fi
 }
-check_next_free "$DEC_FILE" DEC "$TMP/dec_def"
-check_next_free "$OQ_FILE"  OQ  "$TMP/oq_def"
+case "$SHAPE" in
+  register) check_next_free "$DEC_FILE" DEC "$TMP/dec_def" ;;
+  adr)
+    # Count from the FILENAMES, not from the entry index. The index keeps one row
+    # per id on purpose (an entry has one status line), and that dedupe silently
+    # swallowed the very thing this check looks for: a second file claiming a
+    # number already taken. The filename is the allocator, so the filename is what
+    # gets counted. The check was wrong, not the probe.
+    _dupes=$(sed 's|.*/||; s|^\([0-9][0-9]*\)-.*|\1|' "$TMP/adrfiles" | sort | uniq -d | tr '\n' ' ')
+    _adr_n=$(wc -l < "$TMP/adrfiles" | tr -d ' ')
+    if [ -n "$(echo "$_dupes" | tr -d ' ')" ]; then
+      err "duplicate ADR number(s) — two files claim one id: $_dupes"
+    else
+      ok "ADR numbers are unique ($_adr_n files)"
+    fi ;;
+  *) dormant "id allocator — no decision home yet" ;;
+esac
+check_next_free "$OQ_FILE" OQ "$TMP/oq_def"
 
 # ---------- 4. a stated register size equals the computed one ----------
 # Compute, never restate: a number written in prose is a number that goes stale.
-if [ -f "$DEC_FILE" ] && grep -q 'Register size:' "$DEC_FILE" 2>/dev/null; then
-  _stated=$(grep -o 'Register size:\** *\**[0-9][0-9]*' "$DEC_FILE" | head -1 | grep -o '[0-9][0-9]*')
+_size_src=""
+[ "$SHAPE" = "register" ] && _size_src=$DEC_FILE
+if [ -n "$_size_src" ] && grep -q 'Register size:' "$_size_src" 2>/dev/null; then
+  _stated=$(grep -o 'Register size:\** *\**[0-9][0-9]*' "$_size_src" | head -1 | grep -o '[0-9][0-9]*')
   if [ "${_stated:-x}" != "$DECS" ]; then
-    err "$DEC_FILE: states 'Register size: $_stated', computed $DECS"
+    err "$_size_src: states 'Register size: $_stated', computed $DECS"
   else
     ok "stated register size matches the computed one ($DECS)"
   fi
@@ -173,35 +281,27 @@ fi
 # A document named in an entry's "Consequences / affects:" line must cite that
 # entry. Writing down where a decision must propagate and then not propagating is
 # the exact failure the loop exists to prevent.
-if [ ! -f "$DEC_FILE" ]; then
-  dormant "propagation — no $DEC_FILE yet"
-  PROP_MISSING=0
+PROP_MISSING=0
+if [ "$SHAPE" = "none" ]; then
+  dormant "propagation — no decision home yet"
 else
   : > "$TMP/prop"
-  _cur=""
-  while IFS= read -r line; do
-    case "$line" in
-      '### DEC-'*) _cur=$(echo "$line" | grep -o 'DEC-[0-9][0-9]*') ;;
-      *'Consequences / affects:'*)
-        [ -n "$_cur" ] || continue
-        echo "$line" | grep -o '`[^`]*`' | tr -d '`' | while IFS= read -r doc; do
-          case "$doc" in *.md) ;; *) continue ;; esac
-          [ -f "$doc" ] || { echo "$_cur $doc MISSINGFILE" >> "$TMP/prop"; continue; }
-          if grep -q "$_cur" "$doc"; then :; else echo "$_cur $doc NOCITE" >> "$TMP/prop"; fi
-        done ;;
-    esac
-  done < "$(flat_of "$DEC_FILE")"
-  PROP_MISSING=0
+  while IFS="$(printf '\t')" read -r id doc; do
+    [ -n "${doc:-}" ] || continue
+    if [ ! -f "$doc" ]; then echo "$id -> $doc (MISSINGFILE)" >> "$TMP/prop"
+    elif grep -q "$id" "$doc"; then :
+    else echo "$id -> $doc (NOCITE)" >> "$TMP/prop"; fi
+  done < "$TMP/conseq"
   [ -f "$TMP/prop" ] && PROP_MISSING=$(wc -l < "$TMP/prop" | tr -d ' ')
   : > "$TMP/prop_new"
   if [ "$PROP_MISSING" -gt 0 ]; then
-    while read -r id doc why; do
-      _n=$(echo "$id" | sed 's/^DEC-//' | sed 's/^0*//'); [ -n "$_n" ] || _n=0
-      [ "$_n" -ge "$PROP_FLOOR" ] && echo "$id -> $doc ($why)" >> "$TMP/prop_new"
+    while IFS= read -r row; do
+      _n=$(echo "$row" | grep -o '[0-9][0-9]*' | head -1 | sed 's/^0*//'); [ -n "$_n" ] || _n=0
+      [ "$_n" -ge "$PROP_FLOOR" ] && echo "$row" >> "$TMP/prop_new"
     done < "$TMP/prop"
   fi
   if [ -s "$TMP/prop_new" ] 2>/dev/null; then
-    err "decision(s) naming a document that does not cite them (floor DEC-$PROP_FLOOR):"
+    err "entr(y|ies) naming a document that does not cite them (floor $ID_PREFIX-$PROP_FLOOR):"
     sed 's/^/         /' "$TMP/prop_new"
   else
     ok "consequences propagate (backlog below the floor: $PROP_MISSING)"
@@ -211,30 +311,23 @@ fi
 # ---------- 6. supersede / contradict annotates the target ----------
 # One word for "adds to" and "replaces a clause of" is unenforceable, so the
 # markers are distinct and only two of them oblige the target to say so.
-if [ ! -f "$DEC_FILE" ]; then
-  dormant "supersede annotations — no $DEC_FILE yet"
+if [ "$SHAPE" = "none" ]; then
+  dormant "supersede annotations — no decision home yet"
 else
   : > "$TMP/ann"
-  _cur=""
-  while IFS= read -r line; do
-    case "$line" in
-      '### DEC-'*) _cur=$(echo "$line" | grep -o 'DEC-[0-9][0-9]*') ;;
-      *'Supersedes:'*|*'Contradicts:'*)
-        [ -n "$_cur" ] || continue
-        echo "$line" | grep -o 'DEC-[0-9][0-9]*' | while IFS= read -r target; do
-          [ "$target" = "$_cur" ] && continue
-          _status=$(awk -v t="### $target " '
-            index($0, t) == 1 { found = 1; next }
-            found && /^### DEC-/ { exit }
-            found && /Status:/ { print; exit }
-          ' "$(flat_of "$DEC_FILE")")
-          case "$_status" in
-            *"$_cur"*) ;;
-            *) echo "$target: status line does not record that $_cur retires or contradicts it" >> "$TMP/ann" ;;
-          esac
-        done ;;
-    esac
-  done < "$(flat_of "$DEC_FILE")"
+  while IFS="$(printf '\t')" read -r src marker target; do
+    [ -n "${target:-}" ] || continue
+    [ "$marker" = "Refines" ] && continue          # additive: no annotation owed
+    _status=$(grep "^$target	" "$TMP/entries" | head -1 | cut -f3)
+    if [ -z "$_status" ]; then
+      echo "$src $marker $target: target is not a defined entry" >> "$TMP/ann"
+    else
+      case "$_status" in
+        *"$src"*) ;;
+        *) echo "$target: status line does not record that $src ${marker}s it" >> "$TMP/ann" ;;
+      esac
+    fi
+  done < "$TMP/edges"
   if [ -s "$TMP/ann" ] 2>/dev/null; then
     err "unannotated supersede/contradict target(s):"; sed 's/^/         /' "$TMP/ann"
   else
@@ -247,29 +340,22 @@ fi
 # is a line: one marker on it exempts every id on it. That is a real blind spot,
 # measured and accepted — a tighter window produced mostly noise, and a gate that
 # is mostly noise is a gate people switch off.
-if [ ! -f "$DEC_FILE" ]; then
-  dormant "retired residue — no $DEC_FILE yet"
-  RESIDUE=0
+RESIDUE=0
+if [ "$SHAPE" = "none" ]; then
+  dormant "retired residue — no decision home yet"
 else
   : > "$TMP/retired"
-  _cur=""
-  while IFS= read -r line; do
-    case "$line" in
-      '### DEC-'*) _cur=$(echo "$line" | grep -o 'DEC-[0-9][0-9]*') ;;
-      *'Status:'*)
-        [ -n "$_cur" ] || continue
-        case "$line" in
-          *Superseded\ by*|*Reversed*) echo "$_cur" >> "$TMP/retired" ;;
-        esac
-        _cur="" ;;
+  while IFS="$(printf '\t')" read -r id file status; do
+    case "$status" in
+      *Superseded\ by*|*Reversed*) echo "$id" >> "$TMP/retired" ;;
     esac
-  done < "$(flat_of "$DEC_FILE")"
-  RESIDUE=0
+  done < "$TMP/entries"
   if [ -s "$TMP/retired" ] 2>/dev/null; then
     : > "$TMP/res"
     while IFS= read -r f; do
       [ -f "$f" ] || continue
       [ "$f" = "$DEC_FILE" ] && continue
+      case "$f" in "$ADR_DIR"/*) continue ;; esac
       while IFS= read -r rid; do
         grep -n "$rid" "$(flat_of "$f")" 2>/dev/null | while IFS=: read -r ln text; do
           case "$text" in
@@ -294,28 +380,28 @@ fi
 # ---------- 8. status vocabularies are closed ----------
 # An unrecognised status is worse than a missing one: it looks answered, and every
 # check on that row skips in silence.
-if [ -f "$DEC_FILE" ]; then
+if [ "$SHAPE" = "none" ]; then
+  dormant "decision status vocabulary — no decision home yet"
+else
   : > "$TMP/vocab"
-  grep -n 'Status:' "$(flat_of "$DEC_FILE")" 2>/dev/null | while IFS= read -r hit; do
-    case "$hit" in
-      *Accepted*|*Superseded\ by*|*Reversed*|*'`Status`'*) ;;
-      *) echo "$DEC_FILE:${hit%%:*}: unknown decision status -> ${hit#*Status:}" >> "$TMP/vocab" ;;
+  while IFS="$(printf '\t')" read -r id file status; do
+    case "$status" in
+      *Accepted*|*Superseded\ by*|*Reversed*) ;;
+      *) echo "$file: $id has an unknown status ->${status#*Status:}" >> "$TMP/vocab" ;;
     esac
-  done
+  done < "$TMP/entries"
   if [ -s "$TMP/vocab" ] 2>/dev/null; then
     err "decision status vocabulary:"; sed 's/^/         /' "$TMP/vocab"
   else
     ok "decision statuses are inside the closed vocabulary"
   fi
-else
-  dormant "decision status vocabulary — no $DEC_FILE yet"
 fi
 
 if [ -f "$OQ_FILE" ]; then
   : > "$TMP/oqvocab"
   grep -n '^| *OQ-[0-9]' "$(flat_of "$OQ_FILE")" 2>/dev/null | while IFS= read -r row; do
     case "$row" in
-      *'| Open '*|*'| Open|'*|*Open\ \|*|*Resolved→DEC-*|*Dropped*) ;;
+      *'| Open '*|*'| Open|'*|*Open\ \|*|*Resolved→*|*Dropped*) ;;
       *) echo "$OQ_FILE:${row%%:*}: unknown question status" >> "$TMP/oqvocab" ;;
     esac
   done
@@ -362,19 +448,28 @@ else
   # Forward direction is scoped to the "## Registers" table: that table is a CLAIM
   # about what exists. The SSOT table below it legitimately names documents a young
   # project has not written yet, and failing on those would make the gate seed red.
+  # TABLE ROWS ONLY. Reading every backtick in the section swept up the prose note
+  # under the table ("an existing docs/adr/ IS the register") and reported it as a
+  # missing file — a claim the note never made. A row is a claim; a sentence is not.
   : > "$TMP/map"
-  awk '/^## Registers/ { on = 1; next } on && /^## / { exit } on { print }' \
-    "$(flat_of "$MAP_FILE")" | grep -o '`[^`]*\.md`' | tr -d '`' | sort -u > "$TMP/map"
+  awk '/^## Registers/ { on = 1; next } on && /^## / { exit } on && /^\|/ { print }' \
+    "$(flat_of "$MAP_FILE")" | grep -o '`[^`]*`' | tr -d '`' | sort -u > "$TMP/map"
   : > "$TMP/mapmiss"
   while IFS= read -r doc; do
     case "$doc" in *'<'*|*'>'*) continue ;; esac
-    [ -e "$doc" ] || echo "$MAP_FILE names $doc, which does not exist" >> "$TMP/mapmiss"
+    case "$doc" in *.md|*/) ;; *) continue ;; esac
+    [ -e "$doc" ] || [ -e "${doc%/}" ] ||
+      echo "$MAP_FILE names $doc, which does not exist" >> "$TMP/mapmiss"
   done < "$TMP/map"
   for reg in "$DEC_FILE" "$OQ_FILE"; do
     [ -f "$reg" ] || continue
     grep -q "$(basename "$reg")" "$TMP/map" ||
       echo "$reg exists but $MAP_FILE never names it" >> "$TMP/mapmiss"
   done
+  if [ "$SHAPE" = "adr" ]; then
+    grep -q "adr" "$TMP/map" ||
+      echo "$ADR_DIR is this project's decision home but $MAP_FILE never names it" >> "$TMP/mapmiss"
+  fi
   if [ -s "$TMP/mapmiss" ] 2>/dev/null; then
     err "doc map / register disagreement:"; sed 's/^/         /' "$TMP/mapmiss"
   else
@@ -387,5 +482,5 @@ if [ "$FAIL" -ne 0 ]; then
   echo "FAIL: documentation gate"
   exit 1
 fi
-echo "OK: documentation gate — ${DECS:-0} decisions · ${OQS:-0} open questions · propagation backlog ${PROP_MISSING:-0} (floor $PROP_FLOOR) · retired residue ${RESIDUE:-0} (floor $RESIDUE_FLOOR)"
+echo "OK: documentation gate — shape $SHAPE · ${DECS:-0} decisions · ${OQS:-0} open questions · propagation backlog ${PROP_MISSING:-0} (floor $PROP_FLOOR) · retired residue ${RESIDUE:-0} (floor $RESIDUE_FLOOR)"
 exit 0