-
Notifications
You must be signed in to change notification settings - Fork 0
Fix stale policy references in AGENTS.md #185
Copy link
Copy link
Closed
Labels
enhancementNew feature or requestNew feature or requestprio:mediumtype:docsImprovements or additions to documentation.Improvements or additions to documentation.
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.mddoes not duplicate policy content—only point to the canonical docs. - Add a short section in
AGENTS.mdthat clarifies: “If a policy appears to conflict, the canonical doc wins; open an issue to resolve.”
Alternatives Considered
- Leaving
AGENTS.mdas-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.mdresolve 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.mdremain the canonical sources andAGENTS.mdonly references them.
Definition of Done:
AGENTS.mdupdated and reviewed.- Changelog note not required (docs-only).
Reactions are currently unavailable
Metadata
Metadata
Labels
enhancementNew feature or requestNew feature or requestprio:mediumtype:docsImprovements or additions to documentation.Improvements or additions to documentation.