Conflict Resolution

When multiple instruction sources target the same folder, TameAGENTS calls out the winning ancestor so you can fix shadowed rules before they ship.

Nearest agents.md wins

TameAGENTS evaluates every agents.md along the folder path and applies the nearest ancestor, just like configuration cascading in editors. If a child document collides with an ancestor, the child loses unless you promote those rules upward.

repo/
├── agents.md            # Lays down "L2 leash" for everyone
└── apps/api/
    ├── agents.md        # Tightens access to prod DB
    └── routes/payments/
        └── agents.md    # Conflicts with parent, marked as losing

The losing file is highlighted with a warning badge that links to the winning ancestor. “Nearest wins” applies everywhere in the product—Explorer badges, hover hints, and CI output.

Path-scoped Copilot merges

Copilot instructions from .github/copilot-instructions.md and *.instructions.md are flattened into a scoped map. We evaluate every applyTo glob and keep the rule set with the most specific match for the active folder.

# .github/copilot-instructions.md
applyTo: ["**"]
rules:
  - Prefer Vitest.

# frontend.instructions.md
applyTo: ["apps/website/**"]
rules:
  - Never remove Structured Data.

When both globs cover apps/website/app/page.tsx, the folder-scoped instructions win. The global file stays available as context, so reviewers can compare the losing payload before promoting it.

How we surface winners

• Agents Map badges: hovering a folder shows the winning file path and a summary of losing ones.
• Conflict panel: grouped by provider (Agents | VS | C | JB | Ignores) with filters that match the Explorer chips.
• Editor diagnostics: warnings point you directly at the parent document or Copilot file that took precedence.

Remediation workflow

1. Open the losing document via the Conflict panel or the gutter warning.
2. Use “Promote to parent” to copy the relevant rules into the winning scope or adjust the child file.
3. Re-run the Agents Map or CLI to ensure the warning disappears before merging.

CLI for CI pipelines

# Fail builds when conflicts are introduced
tameagents report conflicts --json | tee conflicts.json

# Example JSON payload
{
  "root": ".",
  "conflicts": [
    {
      "category": "agents",
      "scope": "src/app",
      "winning": { "path": "src/agents.md" },
      "losing": { "path": "src/app/agents.md" }
    }
  ]
}

The JSON payload mirrors what you see in the UI—provider, winning path, losing path, and the scope that was evaluated. Feed the output into pre-commit hooks or GitHub Actions to block merges until conflicts are resolved.