artifact-validator

Artifact Validator (Database)

Prevents the agent from creating or committing duplicate database artifacts. Runs as a pre-write gate (before Write/Edit) and as a post-work validation pass.

When to invoke

• Pre-write phase: Before every Write or Edit that creates or modifies a database artifact
• Post-work phase: After agent completes its work, before code-review — scans all session-created files

Parameters (passed by adapter)

• artifactPath — absolute path of the file about to be written (pre-write) or list of all session files (post-work)
• artifactContent — content about to be written (pre-write only)
• engine — resolved database engine (sqlserver | postgres | mongodb | cosmosdb)
• scanDirs — directories to scan for existing artifacts (default: ["db/", "migrations/", "schemas/", "seeds/", "stored-procedures/", "views/", "functions/"])

Duplicate Detection Checks

Check 1 — Exact Path Duplicate (P0 BLOCK)

If artifactPath already exists on disk and the agent is using Write (full file create):

• P0 BLOCK — "File '[path]' already exists. Use Edit to modify an existing file, or choose a different path."

This prevents accidental overwrites of existing artifacts.

Check 2 — Name Collision (P1 BLOCK)

Scan scanDirs for files with the same base name (ignoring timestamp/version prefix):

• Strip common prefixes: V\d+__, \d{8,14}_, \d+_ (version/timestamp patterns)
• Compare normalized base names (case-insensitive)
• For migrations: also compare the operation descriptor (e.g., AddUsers, CreateOrdersTable)

If match found:

• P1 BLOCK — "Artifact '[newName]' has a name collision with existing '[existingPath]'. If this is intentional (e.g., a replacement migration), confirm before proceeding."
• Require human confirmation before writing.

Check 3 — Structural Duplicate Detection (P1 BLOCK)

Parse the artifact content for structural elements and compare against existing files:

SQL artifacts (sqlserver, postgres):

• Extract CREATE TABLE, CREATE INDEX, CREATE VIEW, CREATE PROCEDURE, CREATE FUNCTION names
• Scan existing files in scanDirs for the same object names
• If a file already defines the same object: P1 BLOCK — "Object '[objectName]' is already defined in '[existingFile]'. Creating a duplicate definition will cause deployment conflicts."

MongoDB artifacts:

• Extract collection names from db.createCollection(), mongoose.model(), schema definitions
• Scan for existing collection definitions
• If duplicate: P1 BLOCK — "Collection '[collectionName]' schema is already defined in '[existingFile]'."

Cosmos DB artifacts:

• Extract container names from SDK calls (database.containers.createIfNotExists, container definitions)
• Scan for existing container definitions
• If duplicate: P1 BLOCK — "Container '[containerName]' is already defined in '[existingFile]'."

Check 4 — Content Similarity (P2 WARN + Human Confirmation)

Compare the artifact content against all files in scanDirs using line-level similarity:

1. Normalize both files: strip comments, collapse whitespace, lowercase
2. Compute overlap ratio: shared_lines / max(lines_a, lines_b)
3. Thresholds:
   • >= 0.90 — P1 BLOCK — "New artifact is ≥90% similar to '[existingFile]'. This appears to be a duplicate."
   • >= 0.70 — P2 WARN — "New artifact is ≥70% similar to '[existingFile]'. Review for unintentional duplication."
   • < 0.70 — no action

If similarity is between 0.70 and 0.90: request human confirmation before writing.

Check 5 — Migration Conflict Detection (P1 BLOCK)

For migration files only:

• Check for version/sequence conflicts (two migrations with the same version number)
• Check for contradictory operations (e.g., migration A adds column X, new migration also adds column X)
• Check for orphan references (new migration references a table/column that no prior migration creates)

On conflict: P1 BLOCK — "Migration conflict: [description]. Resolve before proceeding."

Check 6 — Cross-File Orphan Reference (P2 WARN)

For stored procedures, views, and functions:

• Extract referenced tables, columns, and other objects
• Verify each reference exists in the schema (from migration files or schema definitions)
• If unresolved: P2 WARN — "Reference to '[objectName]' not found in current schema. Verify it exists or will be created by a preceding migration."

Ambiguity Rule (Human-in-the-Loop)

If any check produces an ambiguous result — e.g., name similarity is close but not exact, structural overlap is partial, or the agent cannot determine intent:

Do not guess. Do not auto-resolve.

Surface to human:

"I detected a potential duplicate artifact but cannot determine with certainty whether this is intentional. Please review:

• New file: [path]
• Potential duplicate: [existingPath]
• Detection reason: [check name + details]

Should I proceed with writing this file? (yes / no / rename)"

Wait for explicit human confirmation before proceeding. If the human responds:

• yes — proceed, log the override in audit trail
• no — abort the write, log the block in audit trail
• rename — prompt for a new name, re-run validation on the new name

Commit-Time Validation

Before any git add or git commit that includes agent-generated artifacts:

1. Re-run Checks 2-5 against the full repository (not just scanDirs) to catch duplicates introduced outside the current session
2. If any BLOCK-level finding: prevent the commit and surface to human
3. Log all commit-time validation results to the audit trail

Output Format

{
  "artifactValidation": {
    "phase": "pre-write | post-work | commit",
    "artifactPath": "<path>",
    "engine": "<engine>",
    "checks": [
      {
        "check": "exact-path-duplicate | name-collision | structural-duplicate | content-similarity | migration-conflict | orphan-reference",
        "result": "PASS | BLOCK | WARN | HUMAN_REVIEW",
        "severity": "P0 | P1 | P2",
        "detail": "<description>",
        "existingFile": "<path or null>",
        "confidence": 0.0-1.0
      }
    ],
    "overallResult": "PASS | BLOCK | HUMAN_REVIEW",
    "humanConfirmationRequired": true | false,
    "humanResponse": "yes | no | rename | null"
  }
}

Configuration Keys

• artifactValidation.enabled (default: true) — enable/disable duplicate detection
• artifactValidation.similarityThreshold (default: 0.70) — minimum overlap ratio to trigger WARN
• artifactValidation.blockThreshold (default: 0.90) — minimum overlap ratio to trigger BLOCK
• artifactValidation.scanDirs (default: ["db/", "migrations/", "schemas/", "seeds/", "stored-procedures/", "views/", "functions/"]) — directories to scan
• artifactValidation.excludePatterns (default: ["*.bak", "*.tmp", "*.log"]) — file patterns to exclude from comparison
• artifactValidation.commitTimeValidation (default: true) — enable commit-time re-validation

Misconfiguration Warnings

During the post-work phase, the validator also checks for common workspace misconfigurations:

• ChromaDB availability: When memory.vectorStore.enabled is true in the agent or guardrails config but chromadb cannot be imported (not installed), emit a P3 INFO warning: "vectorStore.enabled is true but chromadb is not installed. Vector memory writes will be silently skipped. Install: pip install -r guardrails/guardrails-coding-agent/requirements.txt". This is informational only — never blocks.