Add DocC documentation sync gate

[SoundBlaster]

Summary

• What changed?
• • Added a DocC synchronization contract for mirrored repository documentation.
• • Added tools/validate_docc_sync.py and make docc-sync to validate required anchors across ordinary docs and DocC pages.
• • Documented the mandatory DocC sync rule in AGENTS.md and CONTRIBUTING.md.
• Link related issue/task (if any):
• N/A

Motivation

• Why is this change needed?
• • SpecGraph now publishes DocC as the hosted technical documentation surface, so ordinary repository docs and DocC mirrors need an explicit freshness gate.
• What problem, gap, or user need does it address?
• • Prevents repository docs and Sources/SpecGraph/Documentation.docc/ pages from drifting when operational guidance changes.

Goals

• What should this PR achieve?
• • Add a lightweight, extensible validation script for DocC/docs synchronization.
• • Make the rule visible to both agents and human contributors.
• What is intentionally out of scope?
• • Full DocC content rewrite.
• • Byte-for-byte synchronization between Markdown files with different navigation needs.

Changes

• • Added tools/docc_sync_contract.json with synchronization groups and required anchors.
• • Added tools/validate_docc_sync.py.
• • Added focused pytest coverage in tests/test_docc_sync.py.
• • Added make docc-sync and listed it in Makefile help.
• • Updated AGENTS.md and CONTRIBUTING.md with the DocC synchronization rule.

Validation

• Tests added/updated for changed behavior
• Local checks passed

Commands run:

make docc-sync
python3 -m pytest -q tests/test_docc_sync.py
# pre-commit hooks during commit:
python-quality
spec-yaml-format
spec-yaml-lint
ruff (legacy alias)
ruff format

Results:

• make docc-sync: passed
• python3 -m pytest -q tests/test_docc_sync.py: 1 passed
• Commit hooks: passed or skipped where no matching files existed

Risks / Notes

• Backward compatibility impact:
• • Adds a validation gate only; no runtime behavior changes.
• Migration/config changes required:
• • None.
• Known limitations:
• • The sync contract is anchor-based, not semantic diffing. New documentation areas must be added to tools/docc_sync_contract.json when they become mirrored DocC surfaces.

Checklist

• PR title clearly describes the change
• Scope is focused and minimal
• Documentation updated (or N/A)
• No secrets or sensitive data added

[Copilot]

Pull request overview

Adds a DocC synchronization gate so mirrored hosted documentation and repository Markdown stay aligned on required operational anchors.

Changes:

• Adds an anchor-based DocC sync contract and validation script.
• Adds make docc-sync plus focused pytest coverage.
• Documents the mandatory sync workflow in contributor and agent guidance.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tools/validate_docc_sync.py	Implements contract loading and anchor validation.
tools/docc_sync_contract.json	Defines synchronized doc/DocC groups and required anchors.
tests/test_docc_sync.py	Verifies the checked-in sync contract passes.
Makefile	Adds the docc-sync shortcut and help entry.
CONTRIBUTING.md	Documents the DocC sync rule for contributors.
AGENTS.md	Adds the sync rule to agent operating guidance.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2fa36853fd

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".