forgedock 1.1.1 → 1.1.3

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": []
+}