Manual Review Triggers for Critical Edits

Deterministic gatekeeping that intercepts high-risk spatial changes before they reach production—part of the Conflict Resolution & Team Synchronization Workflows for collaborative GIS teams.

Automated merge strategies handle routine updates efficiently, but they introduce unacceptable risk when applied to boundary realignments, topology-altering geometry shifts, or changes to regulated attribute fields. Without explicit trigger logic a single misaligned parcel or an incorrectly classified land-use code can cascade through downstream spatial joins, breaking analytics and violating compliance mandates. A well-designed review trigger system acts as a circuit breaker: it halts propagation only when predefined risk thresholds are breached and lets low-risk commits merge without delay.

Prerequisites & Environment Setup

Before deploying trigger logic, your geospatial versioning stack must satisfy the following requirements. Skipping these foundations typically produces false positives, pipeline bottlenecks, or unresolvable state conflicts.

• Python 3.10+ with geopandas >= 0.14, shapely >= 2.0, and pyproj >= 3.6 installed in the validation environment. Shapely 2.x is required for the vectorised Hausdorff API.
• Spatial database with branch isolation: PostGIS with temporal extensions, Dolt spatial, or a Git-backed GeoPackage repository must support diff generation and pre-merge hooks.
• Unified projected CRS: all contributing datasets must share a metric projection (EPSG:3857, EPSG:27700, or a national grid appropriate to your region). Trigger logic depends on metric distance thresholds; unprojected EPSG:4326 coordinates produce inaccurate displacement calculations.
• Attribute schema registry: a machine-readable manifest (JSON or YAML) that lists critical fields, acceptable value ranges, and field-dependency rules. This registry drives attribute-level trigger evaluation and prevents silent schema drift from bypassing the gate.
• CI/CD hook integration: a pipeline capable of executing Python validation scripts on pre-commit or pre-merge events. GitHub Actions, GitLab CI, or Jenkins can orchestrate trigger evaluation and queue routing.
• Role-based access control (RBAC): contributor, reviewer, and administrator roles must be clearly separated. Review queues must enforce least-privilege principles to prevent unauthorised approvals.

Core Algorithmic Patterns

1. Hausdorff-Distance Displacement Scoring

Hausdorff distance is the standard metric for measuring worst-case vertex displacement between a baseline and a proposed geometry. Unlike centroid displacement (which misses edge movement) or area delta (which misses shape distortion without area change), Hausdorff distance captures the maximum positional error anywhere on the feature boundary.

For a feature pair (B, P), the Hausdorff distance is:

H(B, P) = max( sup_{b ∈ B} inf_{p ∈ P} d(b,p),
               sup_{p ∈ P} inf_{b ∈ B} d(b,p) )

Shapely’s hausdorff_distance(densify=0.25) approximates this with interpolated points at 25 % of edge length, which is sufficient for displacement thresholds above 0.1 m. Spatial complexity is O(n log n) when vertices are indexed; avoid computing it on full-resolution multipart features with millions of vertices without pre-clipping to the changed extent.

2. Topology Validity Scoring

Topology violations—self-intersecting rings, unclosed polygons, and sliver artifacts—must be caught before displacement scoring, because Hausdorff distance between an invalid and a valid geometry is undefined in Shapely. The automated conflict detection step upstream already flags gross topology errors during branch comparison; the trigger layer applies make_valid as a repair attempt and re-checks validity after repair. Features that remain invalid after repair are hard-blocked regardless of displacement.

3. Attribute Sensitivity Classification

The schema registry maps each field to a sensitivity tier:

Cross-referencing displacement score against attribute tier is what prevents low-displacement edits to a protected field from slipping through the geometry gate alone.

Production Workflow Implementation

Step 1: Generate Spatial and Attribute Diffs

When a contributor opens a pull request or merge request, extract the proposed changeset and compare it against the target branch baseline. Operate only on the changed extent—use a spatial index to limit comparisons to bounding boxes of touched features, not the full dataset.

import geopandas as gpd
from shapely.validation import make_valid


def load_changed_features(
    baseline_path: str,
    proposed_path: str,
    id_col: str = "feature_id",
) -> tuple[gpd.GeoDataFrame, gpd.GeoDataFrame]:
    """Load only features present in both snapshot files, aligned to a shared CRS."""
    base = gpd.read_file(baseline_path)
    prop = gpd.read_file(proposed_path)

    # Repair geometries immediately on load
    prop = prop.copy()
    prop["geometry"] = prop["geometry"].apply(make_valid)

    # Enforce shared CRS before any spatial operation
    if base.crs != prop.crs:
        prop = prop.to_crs(base.crs)

    # Restrict to the changed extent using a spatial join on the bounding union
    changed_ids = set(prop[id_col]).symmetric_difference(set(base[id_col]))
    modified = set(prop[id_col]) & set(base[id_col])
    return (
        base[base[id_col].isin(modified | changed_ids)].copy(),
        prop[prop[id_col].isin(modified | changed_ids)].copy(),
    )

Step 2: Evaluate Risk Tier

Apply configurable thresholds to classify each feature into a risk tier. The function below returns a list of flagged feature IDs and the reason for each flag.

from __future__ import annotations
import json
from pathlib import Path


def evaluate_critical_edits(
    baseline_gdf: gpd.GeoDataFrame,
    proposed_gdf: gpd.GeoDataFrame,
    schema_registry_path: str,
    id_col: str = "feature_id",
    displacement_threshold_m: float = 2.5,
    densify_factor: float = 0.25,
) -> list[dict]:
    """
    Returns a list of {id, reason} dicts for features that must be reviewed.

    displacement_threshold_m: Hausdorff distance in metres above which a geometry
        change is flagged. Calibrate per dataset precision spec.
    densify_factor: interpolation density passed to hausdorff_distance(); 0.25
        (25 % of edge length) balances accuracy and speed.
    """
    registry = json.loads(Path(schema_registry_path).read_text())
    critical_fields: set[str] = {
        f for f, meta in registry["fields"].items()
        if meta.get("tier") in ("critical", "regulated")
    }

    merged = baseline_gdf[[id_col, "geometry"]].merge(
        proposed_gdf[[id_col, "geometry"] + list(critical_fields & set(proposed_gdf.columns))],
        on=id_col,
        suffixes=("_base", "_prop"),
    )

    flagged: list[dict] = []

    for _, row in merged.iterrows():
        fid = row[id_col]
        base_geom = row["geometry_base"]
        prop_geom = row["geometry_prop"]

        # Hard block: topology invalid after repair attempt
        if not prop_geom.is_valid:
            flagged.append({"id": fid, "reason": "invalid_topology_post_repair"})
            continue

        # Displacement trigger
        hd = base_geom.hausdorff_distance(prop_geom, densify=densify_factor)
        if hd > displacement_threshold_m:
            flagged.append({"id": fid, "reason": f"displacement_{hd:.2f}m"})
            continue

        # Attribute sensitivity trigger
        for field in critical_fields:
            base_col = f"{field}_base"
            prop_col = f"{field}_prop"
            if base_col in row and prop_col in row and row[base_col] != row[prop_col]:
                flagged.append({"id": fid, "reason": f"sensitive_field_{field}"})
                break

    return flagged

If flagged is non-empty the pipeline halts and writes results to the review queue. If empty, the merge proceeds automatically.

Step 3: Route to Review Queue

Serialise flagged changesets with context packages and route by domain ownership. The queue entry must include enough context for a reviewer to act without switching tools.

import hashlib, datetime, json
from typing import Any


def build_review_ticket(
    changeset_hash: str,
    branch: str,
    flagged_features: list[dict],
    domain_routing: dict[str, str],
    displacement_threshold: float,
) -> dict[str, Any]:
    """
    Builds a structured review ticket for a flagged spatial changeset.

    domain_routing maps layer name prefixes to reviewer team identifiers,
    e.g. {"hydro_": "hydrology-team", "cadastral_": "survey-team"}.
    """
    team = next(
        (v for k, v in domain_routing.items() if changeset_hash.startswith(k)),
        "gis-operations",
    )
    return {
        "ticket_id": hashlib.sha256(
            f"{changeset_hash}{datetime.datetime.utcnow().isoformat()}".encode()
        ).hexdigest()[:12],
        "branch": branch,
        "changeset_hash": changeset_hash,
        "flagged_features": flagged_features,
        "assigned_team": team,
        "threshold_at_evaluation": displacement_threshold,
        "created_utc": datetime.datetime.utcnow().isoformat(),
        "status": "pending",
    }

Integrate with collaboration tools (Slack, Teams, Jira) via webhooks so reviewers receive actionable notifications. Each ticket should link to a map preview rendered by the pipeline showing the before/after geometries side by side.

Step 4: Execute Reviewer Decision and Merge

On reviewer approval, run a final validation sweep identical to the initial evaluation before executing the merge. This guards against race conditions where the target branch received other commits while the ticket was open.

def approve_and_merge(
    ticket: dict,
    baseline_gdf: gpd.GeoDataFrame,
    proposed_gdf: gpd.GeoDataFrame,
    schema_registry_path: str,
    reviewer_id: str,
    comment: str,
) -> dict:
    """
    Performs a final validation sweep before merge.
    Returns an updated ticket with the approval record and merge status.
    """
    # Re-evaluate: target branch may have changed since ticket was opened
    still_flagged = evaluate_critical_edits(
        baseline_gdf, proposed_gdf, schema_registry_path
    )
    if still_flagged:
        ticket["status"] = "re_flagged"
        ticket["re_flag_reason"] = still_flagged
        return ticket

    ticket["status"] = "approved"
    ticket["reviewer_id"] = reviewer_id
    ticket["reviewer_comment"] = comment
    ticket["approved_utc"] = datetime.datetime.utcnow().isoformat()
    # Actual merge call goes here (git merge, DVC push, DB apply, etc.)
    ticket["merge_status"] = "merged"
    return ticket

Step 5: Write Immutable Audit Records

Every trigger activation, reviewer decision, and merge event must be logged. Append to an immutable store—an object storage bucket with object-lock enabled, or a write-once database table.

import pathlib


def append_audit_record(audit_dir: str, ticket: dict) -> None:
    """
    Appends a JSON line to a per-day audit file.
    Use with an object-lock-enabled bucket mount for regulatory compliance.
    """
    day = datetime.datetime.utcnow().strftime("%Y-%m-%d")
    audit_path = pathlib.Path(audit_dir) / f"audit_{day}.jsonl"
    with audit_path.open("a") as fh:
        fh.write(json.dumps(ticket) + "\n")

These logs feed a continuous improvement loop. By analysing false-positive rates and review cycle times over 30-day rolling windows, teams can recalibrate displacement thresholds, refine attribute sensitivity tiers, and optimise routing logic.

Code Reliability Patterns

Tolerance snapping before comparison. Floating-point precision differences across environments cause non-deterministic trigger behaviour. Normalise coordinates to a fixed precision (e.g., 1 mm = 0.001 m) using shapely.set_precision(geometry, grid_size=0.001) before computing Hausdorff distance.

Default-to-block on validator failure. If the validation service times out or the schema registry is unreachable, the pipeline must block the merge rather than silently approve. Implement a circuit breaker with a configurable wait period (e.g., 30 seconds) and expose a dead-man-switch endpoint that administrators can toggle to enter maintenance mode.

Rollback on post-merge failure. If post-merge topology validation fails (a race condition introduced by a concurrent commit), the pipeline should issue an automatic revert commit and re-queue the original ticket. Track the revert in the audit log so the reviewer sees the full lifecycle.

Idempotent ticket IDs. Derive the ticket ID from a hash of (changeset_hash, branch, evaluation_timestamp_truncated_to_minute) so that duplicate webhook deliveries produce the same ticket rather than flooding the queue.

Test coverage for trigger logic. Treat validation scripts as production code. Maintain a test suite with synthetic geometries covering edge cases: multipart features, Z/M coordinates, empty geometries, and CRS mismatches. The geometry overlap resolution techniques test fixtures are a good starting point for overlapping-polygon edge cases.

Performance & Scale Considerations

Spatial extent filtering before diff. Never diff the full dataset. Compute the union of changed feature bounding boxes and clip the baseline to that extent before loading into memory. A GiST index on the geometry column (CREATE INDEX ON features USING GIST(geometry)) makes this clip sub-second even on million-row tables.

Batch Hausdorff evaluation. Shapely 2.x exposes a vectorised shapely.hausdorff_distance(geoms_a, geoms_b, densify=0.25) that operates on numpy arrays and runs 10–50× faster than a Python loop. For changesets with more than 5 000 modified features, this is mandatory—Python-loop evaluation at that scale can take minutes and will time out CI/CD pipelines.

import numpy as np
import shapely


def batch_hausdorff(base_geoms, prop_geoms, densify: float = 0.25) -> np.ndarray:
    """Vectorised Hausdorff distance for large changesets (Shapely 2.x)."""
    return shapely.hausdorff_distance(
        np.asarray(base_geoms), np.asarray(prop_geoms), densify=densify
    )

Memory-mapped I/O for large GeoPackages. When reading baseline snapshots from GeoPackage files exceeding 1 GB, open with fiona layer chunking (chunk_size=5000) rather than loading the full layer into a GeoDataFrame. Process chunks sequentially and accumulate only the flagged IDs—not the full geometry arrays.

Asynchronous queue serialisation. Write review tickets to the queue asynchronously (e.g., via a message broker) so the validation step does not block the CI/CD job waiting for the queue to acknowledge receipt. Return a 202 Accepted and let the job finish; the broker delivers the ticket independently.

Benchmark reference. On a 16-core VM with 64 GB RAM, the vectorised pipeline evaluates 50 000 modified polygons (average 120 vertices each) against displacement and topology rules in approximately 8 seconds. Python-loop equivalent takes ~7 minutes.

Troubleshooting & Failure Modes

FAQ

What displacement threshold should I start with for parcel boundary edits?

2–5 metres is a practical starting point for cadastral workflows at 1:1 000 scale. Calibrate down to 0.5 m if you are working with survey-grade data and the dataset’s positional accuracy specification demands sub-metre precision. Use audit log data from the first 30 days to tune toward a false-positive rate below 20 %.

How do I prevent review fatigue from too many false positives?

Track false-positive rates per trigger rule over rolling 30-day windows. Rules that fire without resulting in a rejection more than 80 % of the time are candidates for threshold relaxation or demotion to a warning lane rather than a hard review block. The automated patching workflow for minor geometry shifts can absorb a class of low-displacement edits that currently clog the review queue.

Can the same trigger framework cover both vector and raster changes?

Yes, but the diff metrics diverge. Vector triggers compare Hausdorff distance and area delta; raster triggers compare band histograms, pixel-value RMSE, and extent changes. Keep the routing and queue logic shared but swap out the diff engine per dataset type.

What happens if the validation service is unavailable during a merge attempt?

The pipeline must default to a safe state and block the merge. Never silently approve on validator timeout. Implement a circuit breaker with a configurable wait period and escalate to administrators if the service stays down beyond your SLA window.

How should audit logs be stored to satisfy regulatory requirements?

Write to an append-only store: an immutable object store bucket with object-lock enabled, or a write-once database table. Include changeset hash, branch metadata, threshold values at evaluation time, reviewer identity, decision timestamp, and final merge status. Retain records for the period mandated by the applicable standard—typically 5–7 years for environmental or cadastral datasets.

Related

• Geometry Overlap Resolution Techniques — handle overlapping polygons that manual review flags but cannot auto-repair
• Attribute Reconciliation for Tabular Spatial Data — reconcile the sensitive attribute fields that trigger the review gate
• Automated Patching for Minor Geometry Shifts — offload sub-threshold edits from the review queue into automated patch workflows
• Automated Conflict Detection in Merge Requests — the upstream detection step that feeds changesets into this review pipeline
• Back to Conflict Resolution & Team Synchronization Workflows