forgedock 1.0.22 → 1.1.2

package/scripts/check-command-docs-drift.sh

@@ -0,0 +1,198 @@
+#!/usr/bin/env bash
+# check-command-docs-drift.sh
+#
+# Drift check: every installable command spec in commands/ must have a section
+# in docs/site/command-reference.md, and every command section in the reference
+# must have a corresponding spec file.
+#
+# "Installable" means: install: core (or no install: key) in YAML frontmatter.
+# Commands with install: internal or install: extras are excluded.
+#
+# Exit codes:
+#   0 — no drift
+#   1 — drift detected (missing docs or orphaned reference sections)
+#
+# Usage:
+#   bash scripts/check-command-docs-drift.sh [commands-dir] [reference-file]
+#
+# Defaults:
+#   commands-dir   = commands/
+#   reference-file = docs/site/command-reference.md
+
+set -euo pipefail
+
+# Normalise COMMANDS_DIR: strip trailing slash so path arithmetic is consistent
+# regardless of whether the caller passes "commands" or "commands/".
+COMMANDS_DIR="${1:-commands}"
+COMMANDS_DIR="${COMMANDS_DIR%/}"
+REFERENCE="${2:-docs/site/command-reference.md}"
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+# get_install_tier <file>
+# Reads the first `install:` key from YAML frontmatter. Echoes: core | extras | internal
+get_install_tier() {
+  local file="$1"
+  # Read up to 20 lines looking for frontmatter and the install key.
+  local in_fm=0
+  local line_no=0
+  while IFS= read -r line; do
+    line_no=$(( line_no + 1 ))
+    if [ $line_no -eq 1 ]; then
+      if [[ "$line" == "---"* ]]; then in_fm=1; continue; fi
+      # No frontmatter — default to core
+      echo "core"; return
+    fi
+    if [ $in_fm -eq 1 ]; then
+      if [[ "$line" == "---"* ]]; then
+        # End of frontmatter — key not found, default to core
+        echo "core"; return
+      fi
+      if [[ "$line" =~ ^install:[[:space:]]*(.*) ]]; then
+        local val="${BASH_REMATCH[1]}"
+        # Strip surrounding quotes
+        val="${val#\"}" ; val="${val%\"}"
+        val="${val#\'}" ; val="${val%\'}"
+        val="${val// /}"  # trim spaces
+        case "$val" in
+          internal|extras) echo "$val"; return ;;
+          core)            echo "core"; return ;;
+          *)               echo "core"; return ;;
+        esac
+      fi
+    fi
+  done < <(head -25 "$file")
+  echo "core"
+}
+
+# ---------------------------------------------------------------------------
+# 1. Collect installable command names from commands/
+# ---------------------------------------------------------------------------
+
+declare -a INSTALLABLE_COMMANDS=()
+
+while IFS= read -r -d '' spec; do
+  tier="$(get_install_tier "$spec")"
+  if [[ "$tier" == "core" ]]; then
+    # Derive command name from path relative to COMMANDS_DIR.
+    # e.g. commands/work-on.md           → /work-on
+    #      commands/work-on/build.md      → /work-on/build
+    #      commands/work-on/build/impl.md → /work-on/build/impl
+    rel="${spec#${COMMANDS_DIR}/}"
+    cmd="/${rel%.md}"
+    INSTALLABLE_COMMANDS+=("$cmd")
+  fi
+done < <(find "$COMMANDS_DIR" -name '*.md' -print0 | sort -z)
+
+# ---------------------------------------------------------------------------
+# 2. Extract documented command names from command-reference.md
+# ---------------------------------------------------------------------------
+# We look for lines of the form: ### `/some-command`
+# The reference uses backtick-wrapped command names under H3 headings.
+
+declare -a DOCUMENTED_COMMANDS=()
+
+while IFS= read -r line; do
+  # Match H3 heading: ### `/command-name` or ### `/command/sub`
+  if [[ "$line" =~ ^###[[:space:]]+\`(/[a-zA-Z0-9_/-]+)\` ]]; then
+    cmd="${BASH_REMATCH[1]}"
+    DOCUMENTED_COMMANDS+=("$cmd")
+  # Match table cell containing a bare command path: | `/command-name` | ...
+  # This covers the Sub-Phase Commands table which lists commands without H3 headings.
+  # We require the line to look like a markdown table row (starts with |) to avoid
+  # matching inline code examples in prose or fix-instruction blocks.
+  elif [[ "$line" =~ ^\| ]]; then
+    # Extract all backtick-wrapped tokens that look like command paths
+    while [[ "$line" =~ \`(/[a-zA-Z0-9_/-]+)\` ]]; do
+      cmd="${BASH_REMATCH[1]}"
+      DOCUMENTED_COMMANDS+=("$cmd")
+      # Remove the matched portion so the loop can find multiple tokens per line
+      line="${line#*\`${cmd}\`}"
+    done
+  fi
+done < "$REFERENCE"
+
+# Deduplicate DOCUMENTED_COMMANDS (table rows may repeat H3-listed commands)
+declare -a _DEDUPED=()
+declare -A _SEEN=()
+for cmd in "${DOCUMENTED_COMMANDS[@]}"; do
+  if [[ -z "${_SEEN[$cmd]+x}" ]]; then
+    _DEDUPED+=("$cmd")
+    _SEEN[$cmd]=1
+  fi
+done
+DOCUMENTED_COMMANDS=("${_DEDUPED[@]}")
+
+# ---------------------------------------------------------------------------
+# 3. Compare
+# ---------------------------------------------------------------------------
+
+FAIL=0
+
+echo "=== ForgeDock command docs drift check ==="
+echo ""
+echo "Installable specs  : ${#INSTALLABLE_COMMANDS[@]}"
+echo "Documented commands: ${#DOCUMENTED_COMMANDS[@]}"
+echo ""
+
+# 3a. Installable commands missing from the reference
+echo "--- Installable commands not documented in command-reference.md ---"
+MISSING_DOCS=0
+for cmd in "${INSTALLABLE_COMMANDS[@]}"; do
+  found=0
+  for doc_cmd in "${DOCUMENTED_COMMANDS[@]}"; do
+    if [[ "$doc_cmd" == "$cmd" ]]; then
+      found=1
+      break
+    fi
+  done
+  if [[ $found -eq 0 ]]; then
+    echo "  MISSING DOC: $cmd"
+    MISSING_DOCS=$(( MISSING_DOCS + 1 ))
+    FAIL=1
+  fi
+done
+if [[ $MISSING_DOCS -eq 0 ]]; then
+  echo "  OK — all installable commands are documented"
+fi
+echo ""
+
+# 3b. Reference sections whose spec no longer exists (orphaned docs)
+echo "--- Reference sections with no matching installable spec ---"
+ORPHANED=0
+for doc_cmd in "${DOCUMENTED_COMMANDS[@]}"; do
+  found=0
+  for cmd in "${INSTALLABLE_COMMANDS[@]}"; do
+    if [[ "$cmd" == "$doc_cmd" ]]; then
+      found=1
+      break
+    fi
+  done
+  if [[ $found -eq 0 ]]; then
+    echo "  ORPHANED REF: $doc_cmd  (no matching installable spec)"
+    ORPHANED=$(( ORPHANED + 1 ))
+    FAIL=1
+  fi
+done
+if [[ $ORPHANED -eq 0 ]]; then
+  echo "  OK — all reference sections have a matching spec"
+fi
+echo ""
+
+# ---------------------------------------------------------------------------
+# 4. Result
+# ---------------------------------------------------------------------------
+
+if [[ $FAIL -eq 1 ]]; then
+  echo "FAIL: command/docs drift detected."
+  echo ""
+  echo "Fix:"
+  echo "  - MISSING DOC  → add a section for the command to docs/site/command-reference.md"
+  echo "  - ORPHANED REF → remove the section or restore the spec under commands/"
+  exit 1
+else
+  echo "OK: no drift between commands/ and docs/site/command-reference.md"
+  exit 0
+fi

package/scripts/check-protocol-restatements.sh

@@ -0,0 +1,176 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+# check-protocol-restatements.sh — Guard against future restatements of normative
+#                                   FORGE protocol content in commands/**/*.md.
+#
+# ForgeDock keeps three protocol definitions in designated normative source files:
+#
+#   docs/FORGE-PROTOCOL.md       — FORGE annotation format (annotation types,
+#                                   schemas, completion sentinels)
+#   docs/WORKFLOW.md             — Label state machine (workflow:* transitions)
+#   commands/review-pr-agents.md — Evidence-Based Review Protocol (review agent
+#                                   behaviour, structured findings format)
+#
+# Once these are single-sourced, command specs should reference them via a
+# one-line pointer, NOT restate the full content. This script detects
+# heading-level signatures that indicate a full restatement has crept back in.
+#
+# Detected patterns (heading-level restatement signatures):
+#
+#   FORGE_ANNOTATION_PROTOCOL — "# FORGE Annotation Protocol"
+#                                "## FORGE Annotation Protocol"
+#   ANNOTATION_TYPES          — "## Annotation Types"
+#                                "### Annotation Types"
+#   WORKFLOW_STATE_MACHINE    — "# Workflow State Machine"
+#                                "## Workflow State Machine"
+#   LABEL_STATE_MACHINE       — "# Label State Machine"
+#                                "## Label State Machine"
+#   REVIEW_PROTOCOL           — "## Evidence-Based Review Protocol"
+#                                (outside its normative source)
+#
+# Each pattern is keyed to a NORMATIVE_SOURCE — the one file allowed to contain
+# that heading. All other files in commands/ that match are flagged as
+# restatements.
+#
+# Allowlist: to permit a heading in an additional file (e.g. a migration guide),
+# add an HTML comment directly after the heading on the same line:
+#
+#   ## Evidence-Based Review Protocol <!-- allowlist:check-protocol-restatements -->
+#
+# Usage:
+#   check-protocol-restatements.sh [<commands_dir> [<docs_dir>]]
+#     commands_dir: path to the commands/ directory (default: ./commands)
+#     docs_dir:     path to the docs/ directory     (default: ./docs)
+#
+# Exit codes:
+#   0  no restatements found
+#   1  one or more restatement headings found (listed to stderr)
+#   2  usage / dependency error (directory not found)
+#
+# <!-- Added: forge#1270 -->
+
+set -euo pipefail
+
+COMMANDS_DIR="${1:-./commands}"
+DOCS_DIR="${2:-./docs}"
+
+if [ ! -d "$COMMANDS_DIR" ]; then
+  echo "ERROR: commands directory not found: $COMMANDS_DIR" >&2
+  echo "Usage: $0 [<commands_dir> [<docs_dir>]]" >&2
+  exit 2
+fi
+
+if [ ! -d "$DOCS_DIR" ]; then
+  echo "ERROR: docs directory not found: $DOCS_DIR" >&2
+  echo "Usage: $0 [<commands_dir> [<docs_dir>]]" >&2
+  exit 2
+fi
+
+# Normalise paths so comparisons against normative sources work correctly.
+COMMANDS_DIR="$(cd "$COMMANDS_DIR" && pwd)"
+DOCS_DIR="$(cd "$DOCS_DIR" && pwd)"
+REPO_ROOT="$(dirname "$COMMANDS_DIR")"
+
+# ---------------------------------------------------------------------------
+# Pattern table — parallel arrays (same index = one pattern rule)
+#
+# PATTERN_NAMES    : human-readable pattern ID (for error messages)
+# PATTERN_REGEXES  : grep -E regex, anchored to line start (^)
+# NORMATIVE_SOURCES: repo-root-relative path of the one file that MAY contain
+#                    the heading; all other files in commands/ are violations
+# ---------------------------------------------------------------------------
+PATTERN_NAMES=(
+  "FORGE_ANNOTATION_PROTOCOL"
+  "ANNOTATION_TYPES"
+  "WORKFLOW_STATE_MACHINE"
+  "LABEL_STATE_MACHINE"
+  "REVIEW_PROTOCOL"
+)
+
+# Each regex matches one or more heading levels for the given protocol section.
+# Anchored (^) so prose references mid-sentence are not false positives.
+# Trailing content after the key phrase is permitted (e.g. parentheticals like
+# "(ALL Agents Follow)") — the anchored key phrase is the restatement signal.
+# The allowlist comment token exclusion is handled in a separate grep -v pass.
+PATTERN_REGEXES=(
+  "^#{1,2} FORGE Annotation Protocol"
+  "^#{2,3} Annotation Types[[:space:]]*$"
+  "^#{1,2} Workflow State Machine"
+  "^#{1,2} Label State Machine"
+  "^#{1,2} Evidence-Based Review Protocol"
+)
+
+NORMATIVE_SOURCES=(
+  "docs/FORGE-PROTOCOL.md"
+  "docs/FORGE-PROTOCOL.md"
+  "docs/WORKFLOW.md"
+  "docs/WORKFLOW.md"
+  "commands/review-pr-agents.md"
+)
+
+# ---------------------------------------------------------------------------
+# Scan: for each pattern, grep all .md files in commands/, exclude the
+# normative source and allowlisted lines, collect violations.
+# ---------------------------------------------------------------------------
+VIOLATIONS=()
+
+for i in "${!PATTERN_NAMES[@]}"; do
+  pattern_name="${PATTERN_NAMES[$i]}"
+  regex="${PATTERN_REGEXES[$i]}"
+  normative_rel="${NORMATIVE_SOURCES[$i]}"
+  normative_abs="${REPO_ROOT}/${normative_rel}"
+
+  # grep -rn: recursive, print filename:lineno:content
+  # --include: only .md files
+  # We pipe through grep -v to:
+  #   1. Exclude the normative source file itself
+  #   2. Exclude lines carrying the allowlist token
+  while IFS= read -r hit; do
+    [ -n "$hit" ] || continue
+    # hit format: <filepath>:<lineno>:<line_content>
+    filepath="${hit%%:*}"
+    rest="${hit#*:}"
+    lineno="${rest%%:*}"
+    line_content="${rest#*:}"
+
+    # Display a repo-root-relative path for readability.
+    rel_path="${filepath#"${REPO_ROOT}/"}"
+
+    VIOLATIONS+=("${rel_path}:${lineno}: restatement of ${pattern_name}")
+    VIOLATIONS+=("  heading: '${line_content}'")
+  done < <(
+    grep -rnE "$regex" "$COMMANDS_DIR" --include="*.md" 2>/dev/null \
+      | grep -v "^${normative_abs}:" \
+      | grep -v '<!-- allowlist:check-protocol-restatements -->' \
+      || true
+  )
+done
+
+# ---------------------------------------------------------------------------
+# Report and exit.
+# ---------------------------------------------------------------------------
+if [ ${#VIOLATIONS[@]} -gt 0 ]; then
+  echo "ERROR: FORGE protocol restatement heading(s) found in commands/:" >&2
+  echo "" >&2
+  for v in "${VIOLATIONS[@]}"; do
+    echo "  $v" >&2
+  done
+  echo "" >&2
+  echo "These headings indicate a full restatement of normative protocol content." >&2
+  echo "Replace the section with a one-line pointer to the normative source, e.g.:" >&2
+  echo "  > Protocol reference: see docs/FORGE-PROTOCOL.md" >&2
+  echo "" >&2
+  echo "To permit a heading in this file intentionally, add the allowlist token:" >&2
+  echo "  ## <Heading> <!-- allowlist:check-protocol-restatements -->" >&2
+  echo "" >&2
+  echo "Normative sources (these files may contain the headings):" >&2
+  echo "  docs/FORGE-PROTOCOL.md       — FORGE annotation format" >&2
+  echo "  docs/WORKFLOW.md             — Label state machine" >&2
+  echo "  commands/review-pr-agents.md — Evidence-Based Review Protocol" >&2
+  exit 1
+fi
+
+echo "OK: No FORGE protocol restatement headings detected in $COMMANDS_DIR"
+exit 0

package/scripts/check-registry/README.md

@@ -0,0 +1,72 @@
+# ForgeDock Check Registry
+
+The check registry is the feedback edge from review findings back into deterministic quality-gate enforcement. When the same defect class (identified by its `FORGE:PATTERN` tag) recurs 3+ times in a pipeline health window, `/pipeline-health` Phase 4 emits a check-promotion issue. Once the check is written and merged, it is registered here and runs automatically in Step 2 of `/quality-gate`.
+
+## How it works
+
+```
+Review finding filed
+  → FORGE:PATTERN tag added to issue body (review-pr.md Phase 6C)
+  → pipeline-health Phase 4 counts pattern recurrences across issues
+  → at threshold (3+): emits check-promotion issue referencing all source findings
+  → check is written (LLM, once) and placed in scripts/check-registry/
+  → check is registered in manifest.json
+  → quality-gate.md Step 2 runs all registered checks — blocks commit on match
+```
+
+## manifest.json schema
+
+Each entry in the `checks` array:
+
+```json
+{
+  "slug": "migration-number-collision",
+  "description": "Detects duplicate migration number prefixes (e.g. two 0220_*.sql files)",
+  "pattern_tag": "migration-number-collision",
+  "script": "scripts/check-registry/migration-number-collision.sh",
+  "source_findings": ["#1234", "#1298", "#1315"],
+  "promoted_at": "2026-07-04",
+  "severity": "HIGH",
+  "domains": ["DATABASE"]
+}
+```
+
+Fields:
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `slug` | yes | Unique identifier, matches the `FORGE:PATTERN` slug and the script filename |
+| `description` | yes | One sentence: what the check detects |
+| `pattern_tag` | yes | The slug used in `<!-- FORGE:PATTERN: {slug} -->` annotations on finding issues |
+| `script` | yes | Relative path from repo root to the executable check script |
+| `source_findings` | yes | Issue numbers of the review findings that triggered promotion (minimum 3) |
+| `promoted_at` | yes | ISO date when the check was added to the registry |
+| `severity` | yes | `HIGH` (blocks commit) or `MEDIUM` (warning) |
+| `domains` | yes | Quality-gate domain(s) that trigger this check (used for domain-scoped runs) |
+
+## Check script contract
+
+Each check script:
+
+- **Receives**: A space-separated list of changed files on `$1` (same format as `{CHANGED_FILES}` in quality-gate.md), and the worktree path on `$2`.
+- **Exits 0**: No match — check passed.
+- **Exits 1**: Match found — check failed. Print one line per finding to stdout in the format: `{SLUG} | {SEVERITY} | {file:line} | {description}`
+- **Exits 2**: Check not applicable (no relevant files in changeset) — treated as pass.
+- **Runtime**: Must complete in ≤5s for a typical change set. Registry checks add ≤5s total to gate runtime.
+- **No side effects**: Must not write files, network calls, or modify git state.
+
+Example output on exit 1:
+
+```
+migration-number-collision | HIGH | migrations/0220_add_user_table.sql | Duplicate migration prefix 0220 — migrations/0220_existing.sql already uses this prefix
+```
+
+## Adding a new check
+
+1. Write `scripts/check-registry/{slug}.sh` following the contract above.
+2. Test it: `bash scripts/check-registry/{slug}.sh "path/to/changed/file" /path/to/repo`
+3. Add an entry to `manifest.json`.
+4. PR and merge — the check runs on all subsequent quality-gate invocations.
+
+<!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->

package/scripts/check-registry/manifest.json

@@ -0,0 +1,6 @@
+{
+  "_comment": "ForgeDock check-registry manifest — promoted checks from recurring review findings.",
+  "_version": "1",
+  "_docs": "See scripts/check-registry/README.md for the full specification.",
+  "checks": []
+}