Slim agent infrastructure: navigation policy, rubric framework, RIG, cleanup

[johnml1135]

Summary

Overhaul the AI agent infrastructure to be leaner, more structured, and research-informed.

Changes

Removed (~67 files)

• Per-folder verbose AGENTS.md files throughout Src/ — replaced by centralized guidance
• 10 Python hash/check/scaffold scripts (.github/*.py) — replaced by RIG
• CI gate workflow for AGENTS docs
• All Beads tooling, scripts, config, and assets

Added

• Repository Intelligence Graph (RIG): Repository.Intelligence.Graph.json + generator script Build/Agent/Generate-RepositoryIntelligenceGraph.ps1 — deterministic project/build/test topology map
• Navigation policy: .github/instructions/navigation.instructions.md — structural vs semantic task classification, Veto protocol for hidden dependencies, checklist-at-END placement (informed by CodeCompass arXiv:2602.20048)
• Rubric framework (.github/rubrics/):
  • Base schema v2 with 4 equally-weighted categories (file_change, spec_alignment, integrity, runtime), 3 hard gates, 16 atomic criteria with evidence fields
  • 4 specializations: interop-boundary, installer-deployment, parser-grammar, ui-build-workflow
  • Design informed by Agentic Rubrics arXiv:2601.04171 with key improvements: atomic single-predicate criteria, mandatory evidence fields, outcome-based checks, focusCriteria boost semantics
• Rubric verification skill: .github/skills/rubric-verify/SKILL.md — 5-step workflow (select rubric → identify evidence → score → gates → verdict)

Modified

• AGENTS.md — simplified, added RIG/navigation/Serena references
• .github/AGENTS.md — added navigation + rubric references
• .github/AI_GOVERNANCE.md — added navigation.instructions.md to curated keep set
• Skills (verify-test, review, jira-bugfix) — added rubric-verify cross-references
• ~40 OpenSpec spec files — removed dead AGENTS.md links

Rubric quality improvements (v2)

Based on literature review of agentic evaluation research:

• Atomicity: each criterion tests a single observable predicate (no compound "A and B" checks)
• Evidence-grounded: every criterion has an evidence field specifying what artifact to cite
• Balanced weights: all 4 categories at 0.25 (runtime was underweighted at 0.20)
• Hard gates are mechanically verifiable: build exits 0, no new unsanitized boundary input, evidence present — not subjective judgments
• focusCriteria semantics defined: 1.5x weight boost for specialization-relevant criteria
• requiredCommands at base level: build.ps1 + test.ps1 always required
• Renamed for clarity: deterministic_verification + environment_parity → verification_reproducibility; marshalling_risk_reviewed → marshalling_verified (outcome, not process)
• Added: test_coverage criterion, no_regression criterion

Testing

Agent infrastructure changes — no runtime code affected. Validated YAML structure and cross-references.

---

This change is 

[github-actions]

NUnit Tests

    1 files  ±0      1 suites  ±0   6m 2s ⏱️ -3s
4 407 tests ±0  4 320 ✅ ±0  87 💤 ±0  0 ❌ ±0 
4 416 runs  ±0  4 329 ✅ ±0  87 💤 ±0  0 ❌ ±0 

Results for commit 18fbfc7. ± Comparison against base commit db65176.

♻️ This comment has been updated with latest results.

[Copilot]

Pull request overview

Refactors the repo’s AI/agent infrastructure to a slimmer, centralized model by removing per-folder AGENTS sprawl and Beads tooling, and introducing a deterministic Repository Intelligence Graph (RIG), navigation policy, and a weighted rubric framework for verification.

Changes:

• Removed numerous Src/**/AGENTS.md files and related Python automation/CI gate in favor of centralized guidance.
• Added a rubric framework + rubric-verify skill for evidence-grounded scoring and hard-gate verdicts.
• Added navigation policy and updated docs/tooling (README, VS Code tasks) to point to RIG regeneration and the new processes.

Reviewed changes

Copilot reviewed 121 out of 174 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
Src/xWorks/AGENTS.md	Removes per-folder AGENTS documentation (centralization).
Src/XCore/xCoreTests/AGENTS.md	Removes per-folder AGENTS documentation (centralization).
Src/XCore/xCoreInterfaces/AGENTS.md	Removes per-folder AGENTS documentation (centralization).
Src/XCore/SilSidePane/AGENTS.md	Removes per-folder AGENTS documentation (centralization).
Src/XCore/FlexUIAdapter/AGENTS.md	Removes per-folder AGENTS documentation (centralization).
Src/XCore/AGENTS.md	Removes per-folder AGENTS documentation (centralization).
Src/Utilities/XMLUtils/AGENTS.md	Removes per-folder AGENTS documentation (centralization).
Src/Utilities/SfmToXml/AGENTS.md	Removes per-folder AGENTS documentation (centralization).
Src/Utilities/SfmStats/AGENTS.md	Removes per-folder AGENTS documentation (centralization).
Src/Utilities/Reporting/AGENTS.md	Removes per-folder AGENTS documentation (centralization).
Src/Utilities/MessageBoxExLib/AGENTS.md	Removes per-folder AGENTS documentation (centralization).
Src/Utilities/FixFwData/AGENTS.md	Removes per-folder AGENTS documentation (centralization).
Src/Utilities/AGENTS.md	Removes parent-folder AGENTS overview (centralization).
Src/UnicodeCharEditor/AGENTS.md	Removes per-folder AGENTS documentation (centralization).
Src/ProjectUnpacker/AGENTS.md	Removes per-folder AGENTS documentation (centralization).
Src/ParatextImport/AGENTS.md	Removes per-folder AGENTS documentation (centralization).
Src/ManagedVwWindow/AGENTS.md	Removes per-folder AGENTS documentation (centralization).
Src/ManagedVwDrawRootBuffered/AGENTS.md	Removes per-folder AGENTS documentation (centralization).
Src/LexText/LexTextDll/AGENTS.md	Removes per-folder AGENTS documentation (centralization).
Src/LexText/FlexPathwayPlugin/AGENTS.md	Removes per-folder AGENTS documentation (centralization).
Src/LexText/AGENTS.md	Removes parent-folder AGENTS overview (centralization).
Src/Kernel/AGENTS.md	Removes per-folder AGENTS documentation (centralization).
Src/InstallValidator/AGENTS.md	Removes per-folder AGENTS documentation (centralization).
Src/Generic/AGENTS.md	Removes per-folder AGENTS documentation (centralization).
Src/GenerateHCConfig/AGENTS.md	Removes per-folder AGENTS documentation (centralization).
Src/FwResources/AGENTS.md	Removes per-folder AGENTS documentation (centralization).
Src/FwParatextLexiconPlugin/AGENTS.md	Removes per-folder AGENTS documentation (centralization).
Src/FwCoreDlgs/AGENTS.md	Removes per-folder AGENTS documentation (centralization).
Src/FdoUi/AGENTS.md	Removes per-folder AGENTS documentation (centralization).
Src/FXT/AGENTS.md	Removes per-folder AGENTS documentation (centralization).
Src/DocConvert/AGENTS.md	Removes per-folder AGENTS documentation (centralization).
Src/DebugProcs/AGENTS.md	Removes per-folder AGENTS documentation (centralization).
Src/DbExtend/AGENTS.md	Removes per-folder AGENTS documentation (centralization).
Src/Common/ViewsInterfaces/AGENTS.md	Removes per-folder AGENTS documentation (centralization).
Src/Common/UIAdapterInterfaces/AGENTS.md	Removes per-folder AGENTS documentation (centralization).
Src/Common/ScriptureUtils/AGENTS.md	Removes per-folder AGENTS documentation (centralization).
Src/Common/RootSite/AGENTS.md	Removes per-folder AGENTS documentation (centralization).
Src/Common/FwUtils/AGENTS.md	Removes per-folder AGENTS documentation (centralization).
Src/Common/Controls/AGENTS.md	Removes per-folder AGENTS documentation (centralization).
Src/Common/AGENTS.md	Removes parent-folder AGENTS overview (centralization).
Src/Cellar/AGENTS.md	Removes per-folder AGENTS documentation (centralization).
Src/AGENTS.md	Adds minimal, centralized guidance for work under Src/.
ReadMe.md	Updates agent-docs section to reference the minimal AGENTS model + RIG regeneration.
FLExInstaller/wix6/AGENTS.md	Removes WiX6 subfolder AGENTS guidance (centralization).
FLExInstaller/AGENTS.md	Replaces verbose installer AGENTS with a minimal “defaults/constraints” guide.
Docs/agent-docs-refresh.md	Rewrites refresh workflow to match the minimal AGENTS + RIG model.
.vscode/tasks.json	Removes Beads/Jira tasks and adds an “Agent: Generate RIG” task.
.github/workflows/copilot-docs-detect.yml	Removes the agent-docs detection workflow.
.github/skills/verify-test/SKILL.md	Cross-references rubric-verify as an option for execution-free scoring.
.github/skills/rubric-verify/SKILL.md	Adds rubric verification skill workflow with evidence and hard gates.
.github/skills/review/SKILL.md	Cross-references rubric-verify for scoring/hard-gate assessment.
.github/skills/openspec-beads-import/SKILL.md	Removes the OpenSpec→Beads import skill.
.github/skills/jira-to-beads/scripts/export_jira_assigned.py	Removes Jira export script as part of Beads/tooling removal.
.github/skills/jira-to-beads/SKILL.md	Removes Jira→Beads skill.
.github/skills/execute-implement/SKILL.md	Updates notes, removing Beads references and pointing to Jira/PR updates.
.github/skills/beads/resources/WORKTREES.md	Removes Beads resource documentation.
.github/skills/beads/resources/STATIC_DATA.md	Removes Beads resource documentation.
.github/skills/beads/resources/RESUMABILITY.md	Removes Beads resource documentation.
.github/skills/beads/resources/ISSUE_CREATION.md	Removes Beads resource documentation.
.github/skills/beads/resources/CHEMISTRY_PATTERNS.md	Removes Beads resource documentation.
.github/skills/beads/resources/ASYNC_GATES.md	Removes Beads resource documentation.
.github/skills/beads/resources/AGENTS.md	Removes Beads resource documentation.
.github/skills/beads/adr/0001-bd-prime-as-source-of-truth.md	Removes Beads ADR.
.github/skills/beads/SKILL.md	Removes Beads skill.
.github/skills/beads/README.md	Removes Beads skill README.
.github/skills/beads/CLAUDE.md	Removes Beads skill maintenance doc.
.github/skills/atlassian-readonly-skills/SKILL.md	Removes references to the deleted jira-to-beads helper.
.github/rubrics/ui-build-workflow.rubric.yaml	Adds specialized rubric for UI/build workflow changes.
.github/rubrics/parser-grammar.rubric.yaml	Adds specialized rubric for parser/grammar changes.
.github/rubrics/interop-boundary.rubric.yaml	Adds specialized rubric for native/managed/COM boundary changes.
.github/rubrics/installer-deployment.rubric.yaml	Adds specialized rubric for installer/deployment changes.
.github/rubrics/fieldworks-rubric.base.yaml	Adds the base rubric schema v2 with weighted categories and hard gates.
.github/migrate_copilot_format.py	Removes legacy AGENTS migration helper.
.github/instructions/terminal.instructions.md	Removes Beads CLI auto-approval guidance.
.github/instructions/navigation.instructions.md	Adds the navigation policy for structural vs semantic tasks + veto protocol.
.github/copilot_tree_hash.py	Removes legacy tree-hash helper used by the old AGENTS pipeline.
.github/copilot_doc_utils.py	Removes legacy markdown helper utilities for the old AGENTS pipeline.
.github/copilot_change_utils.py	Removes legacy change classification utilities for the old AGENTS pipeline.
.github/copilot_cache.py	Removes legacy cache helper used by the old AGENTS pipeline.
.github/copilot_apply_updates.py	Removes legacy auto-section application script for old per-folder AGENTS.
.github/AI_GOVERNANCE.md	Adds navigation.instructions.md to the curated keep set.
.gitattributes	Removes Beads merge driver config (consistent with Beads removal).

[jasonleenaylor]

@jasonleenaylor reviewed 43 files and all commit messages, and made 4 comments.
Reviewable status: 43 of 177 files reviewed, 1 unresolved discussion (waiting on johnml1135).

---

.github/instructions/navigation.instructions.md line 23 at r2 (raw file):

## Required workflow
1. Start with RIG project/topology lookup.

Are we sure the agents actually interpret this and use the 'Repository.Intelligence.Graph.json'?

---

.github/rubrics/fieldworks-rubric.base.yaml line 1 at r2 (raw file):

schemaVersion: 2

This file seems to be based on a standard or some guidance, it would be good to document that in this file with a comment to help future maintenance.

---

.github/rubrics/ui-build-workflow.rubric.yaml line 16 at r2 (raw file):

specialChecks:
  - id: localization_compliance
    check: Translatable UI strings use .resx files following crowdin.json conventions.

I don't think 'following crowdin.json conventions' adds anything but confusion here.

---

Build/Agent/Generate-RepositoryIntelligenceGraph.ps1 line 153 at r2 (raw file):

$projectFiles = Get-ChildItem -Path (Join-Path $repoRoot "Src") -Recurse -File -Include *.csproj,*.vcxproj,*.wixproj
$projectFiles += Get-ChildItem -Path (Join-Path $repoRoot "FLExInstaller") -Recurse -File -Include *.wixproj

Lib, and I think Andy Black's work in progress will add another root folder with project files we should map.