artifact-validator

Artifact Validator (Frontend)

Prevents the agent from creating or committing duplicate frontend 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 frontend 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)
• framework — resolved framework (react | angular)
• componentType — from component-detection skill (page | component | hook | layout | utility | style)
• scanDirs — directories to scan for existing artifacts (default: ["src/", "components/", "pages/", "app/", "hooks/", "layouts/", "utils/", "styles/", "lib/"])

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 — Component Name Collision (P1 BLOCK)

Scan scanDirs for files defining a component/hook/utility with the same name:

React artifacts:

• Extract component names from export default function X, export const X, function X, const X: React.FC
• Scan for existing components with the same PascalCase name across all component directories
• Check both file-level (UserProfile.tsx) and named exports (export function UserProfile)
• If match found: P1 BLOCK — "Component '[name]' is already defined in '[existingFile]'."

Angular artifacts:

• Extract component/directive/pipe/service names from @Component, @Directive, @Pipe, @Injectable decorators
• Extract the selector value from @Component({ selector: '...' })
• Scan for existing selectors and class names
• If duplicate selector: P1 BLOCK — "Angular selector '[selector]' is already registered in '[existingFile]'. Duplicate selectors cause runtime conflicts."
• If duplicate class name: P1 BLOCK — "Class '[name]' is already defined in '[existingFile]'."

For all frameworks, also check:

• Hook name collision (e.g., useAuth defined in two files)
• Utility function name collision (e.g., formatDate exported from two modules)

If match found: Require human confirmation before writing.

Check 3 — Route / Page Path Duplicate (P1 BLOCK)

For page/route files:

React (Next.js / React Router):

• Extract route paths from file-system routing (pages/, app/ directory structure) or explicit route definitions (<Route path="...">, createBrowserRouter)
• If a new page file would map to the same URL path as an existing page: P1 BLOCK — "Route path '[path]' is already served by '[existingFile]'. Duplicate routes cause ambiguous navigation."

Angular:

• Extract route paths from RouterModule.forRoot([...]), RouterModule.forChild([...]), Routes arrays, and standalone route configs
• If duplicate path: P1 BLOCK — "Route path '[path]' 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, remove import 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 — Style Definition Duplicate (P2 WARN)

For style files (CSS, SCSS, CSS Modules, styled-components, Tailwind config):

• Extract class names, CSS custom properties, styled-component names, and Tailwind layer extensions
• Scan existing style files for the same definitions
• If duplicate class/variable: P2 WARN — "CSS class/variable '[name]' is already defined in '[existingFile]'. This may cause style conflicts or dead code."

For component-scoped styles (CSS Modules, Angular styleUrls): skip this check (scoped by design).

Check 6 — Module Re-export / Barrel Conflict (P2 WARN)

For index files (index.ts, index.js) and barrel exports:

• Extract all re-exports (export { X } from '...', export * from '...')
• Check if the new file would introduce a naming conflict in the barrel (two different modules exporting the same name)
• If conflict: P2 WARN — "Export name '[name]' would conflict with existing re-export from '[existingModule]' in barrel file '[barrelFile]'."

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]
• Component type: [componentType]

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>",
    "framework": "<framework>",
    "componentType": "<componentType>",
    "checks": [
      {
        "check": "exact-path-duplicate | component-name-collision | route-path-duplicate | content-similarity | style-definition-duplicate | barrel-conflict",
        "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/", "components/", "pages/", "app/", "hooks/", "layouts/", "utils/", "styles/", "lib/"]) — directories to scan
• artifactValidation.excludePatterns (default: ["*.bak", "*.tmp", "*.log", "node_modules/", "dist/", ".next/", ".angular/"]) — 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.