Fix stale policy references in AGENTS.md

[Copilot]

AGENTS.md referenced 6 non-existent policy documents due to repository restructuring. This breaks policy discoverability for contributors and agents.

Changes

Updated references to canonical locations:

• docs/advanced/security.md → docs/about/security.md
• docs/advanced/testing.md → docs/develop/testing.md
• docs/advanced/provider-capabilities.md → docs/reference/capabilities.md
• docs/reference/providers-and-contracts.md → docs/extend/providers.md
• docs/reference/steps-and-metadata.md → docs/extend/steps.md
• docs/reference/events-and-observability.md → docs/extend/events.md

Added conflict resolution guidance (Section 9):

• Documents precedence hierarchy when policies conflict: domain docs > root policy docs > AGENTS.md
• Explicit instruction to open issues for unclear conflicts

Enhanced policy navigation (Section 10):

• Added explicit mappings for testing guidance, capability rules, event patterns, provider contracts, step metadata
• Centralizes knowledge of where each policy type lives

All 14 markdown references in AGENTS.md verified to exist. Documentation consistency checks pass with 0 link issues.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Fix stale policy references in AGENTS.md</issue_title>
<issue_description>## Problem Statement

AGENTS.md currently contains references to policy / guideline documents that no longer exist (or have been renamed/moved). This breaks policy discoverability for contributors and agents and undermines the project's guardrails, which in turn increases the risk of inconsistent or insecure changes.

Proposed Solution

Update AGENTS.md so that every referenced policy/guideline document:

• Exists in the repository at the referenced path, or
• Is replaced by the correct canonical document, or
• Is removed if obsolete, with an explicit pointer to the canonical replacement (single source of truth).

Requirements:

• Identify the canonical locations for:
  • Contribution rules / DoD
  • Style rules
  • Security boundaries / redaction guidance
  • Documentation generation rules (if applicable)
• Ensure AGENTS.md does not duplicate policy content—only point to the canonical docs.
• Add a short section in AGENTS.md that clarifies: “If a policy appears to conflict, the canonical doc wins; open an issue to resolve.”

Alternatives Considered

• Leaving AGENTS.md as-is and relying on contributors to “find the right doc”.
  • Rejected: contradicts the consistency principle and increases drift risk.
• Duplicating full policy sections in AGENTS.md.
  • Rejected: creates inevitable inconsistencies over time.

Impact

• Does this affect existing workflows?
  • No runtime impact. Documentation-only change.
• Any backward compatibility concerns?
  • None.

Acceptance Criteria:

• All links/paths referenced from AGENTS.md resolve to existing files.
• For each previous stale reference, the new canonical reference is documented (or removed with rationale).
• CI/doc tooling (if any) remains unaffected.

Additional Context

Verification steps:

• Run a link/path validation pass (manual: verify file existence; optional: add a simple CI check in the future—out of scope for this issue unless already trivial).
• Confirm that README.md / CONTRIBUTING.md / STYLEGUIDE.md / SECURITY.md remain the canonical sources and AGENTS.md only references them.

Definition of Done:

• AGENTS.md updated and reviewed.
• Changelog note not required (docs-only).
  </issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Fix stale policy references in AGENTS.md #185

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[Copilot]

Pull request overview

This PR fixes broken documentation references in AGENTS.md following a repository restructuring that moved policy documents to new locations. The changes improve policy discoverability for both human contributors and automated agents by updating all stale references to their canonical locations and adding explicit guidance for conflict resolution.

Changes:

• Updated 6 stale documentation references to point to their current canonical locations
• Added Section 9 with clear conflict resolution guidance and document precedence hierarchy
• Enhanced Section 10 (renumbered from 9) with explicit mappings for all major policy document types
• Added security vulnerability checklist item referencing SECURITY.md