Skip to content

Fix stale policy references in AGENTS.md #185

@blindzero

Description

@blindzero

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).

Metadata

Metadata

Labels

enhancementNew feature or requestprio:mediumtype:docsImprovements or additions to documentation.

Projects

No projects

Relationships

None yet

Development

No branches or pull requests

Issue actions