artifact-validator

Artifact Validator (Backend)

Prevents the agent from creating or committing duplicate backend code 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 backend source file
• 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)
• language — resolved language (csharp | golang | java | nodejs)
• scanDirs — directories to scan for existing artifacts (default: ["src/", "lib/", "controllers/", "services/", "repositories/", "models/", "middleware/", "tests/"])

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 (case-insensitive, ignoring extension differences for the same language):

Language-specific rules:

Language	Collision scope	Example
C#	Same class/interface name across *.cs files in the project	UserService.cs vs UserService.cs in different folders
Go	Same package + exported function/type name across *.go files	user_service.go defining UserService vs another user_service.go
Java	Same fully-qualified class name across *.java files	com.app.UserService in two locations
Node.js	Same module name across *.ts/*.js files in the same layer	userService.ts vs UserService.ts

If match found:

• P1 BLOCK — "Artifact '[newName]' has a name collision with existing '[existingPath]'. If this is intentional (e.g., overriding in a different layer), 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:

C# artifacts:

• Extract class/interface/record names, namespace, and public method signatures
• Scan for existing types with the same name or identical method signatures
• If a file already defines the same type in the same namespace: P1 BLOCK

Go artifacts:

• Extract exported types (type X struct), function signatures, interface definitions
• Scan for same-named exported symbols in the same package
• If duplicate exported symbol: P1 BLOCK

Java artifacts:

• Extract class/interface names, package declaration, public method signatures
• Scan for same fully-qualified type
• If duplicate: P1 BLOCK

Node.js artifacts:

• Extract exported class/function/const names (export class, export function, module.exports)
• Scan for same-named exports in the same directory or layer
• If duplicate export: P1 BLOCK

Detail: "Type/symbol '[name]' is already defined in '[existingFile]'. Creating a duplicate will cause compilation/import conflicts."

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, remove import/using statements
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 — API Route / Endpoint Duplicate (P1 BLOCK)

For controller/handler files:

• Extract HTTP route definitions:
  • C#: [Route("...")], [HttpGet("...")], [HttpPost("...")], etc.
  • Go: r.HandleFunc("...", ...), e.GET("...", ...), framework-specific route registrations
  • Java: @RequestMapping("..."), @GetMapping("..."), @PostMapping("..."), etc.
  • Node.js: router.get("..."), app.post("..."), @Get("..."), @Post("...") (NestJS)
• Scan all existing controller/handler files for the same route + HTTP method combination
• If duplicate route: P1 BLOCK — "Route '[method] [path]' is already defined in '[existingFile]'. Duplicate routes will cause runtime conflicts."

Check 6 — DI Registration Duplicate (P2 WARN)

For dependency injection registration files (Startup.cs, Program.cs, module files):

• Extract service registrations (AddScoped<T>, AddSingleton<T>, bind(X).to(Y), providers: [...])
• Check if the same service interface is being registered to multiple implementations without explicit named/keyed resolution
• If duplicate registration: P2 WARN — "Service '[interfaceName]' is already registered in '[existingFile]'. Multiple registrations may cause runtime resolution ambiguity."

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>",
    "language": "<language>",
    "checks": [
      {
        "check": "exact-path-duplicate | name-collision | structural-duplicate | content-similarity | api-route-duplicate | di-registration-duplicate",
        "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: ["src/", "lib/", "controllers/", "services/", "repositories/", "models/", "middleware/", "tests/"]) — directories to scan
• artifactValidation.excludePatterns (default: ["*.bak", "*.tmp", "*.log", "bin/", "obj/", "node_modules/", "vendor/"]) — file/directory patterns to exclude
• 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.