docs: add concise agent and PR readiness guidance

[Rana Singh (ranadeepsingh)]

Summary

• replace the long root guide with a concise decision-oriented AGENTS.md
• add synapseml-pr-loop for repeatable 5/5 merge-readiness work
• add synapseml-branches with focused context for master, spark3.5, spark4.0, spark4.1, and unlisted targets
• keep Spark 4 context concise through a shared template and branch overlays templatized from chore: sync spark4.1 with master #2645 and chore: sync spark4.0 with master #2646
• map master and spark3.5 to branch-spark3p5.md, with separate sync rules
• require lifecycle cleanup for recently closed work, follow-up rebases/closures, and current human-readable PR metadata
• encode historical false-confidence cases: stale targets, blocking votes, suppressed comments, unselected suites, path-filter bypasses, unshipped artifacts, and target-branch CI gaps

Why

Recent SynapseML PRs showed that green aggregate CI is insufficient. Agents must resolve context from the PR base branch, verify the target branch's live build and CI definitions, prove the public shipped path, inspect every review surface, and recheck context before implementation, validation, and final push.

Detailed checklists remain in focused references so the always-loaded guidance stays terse.

Validation

• all relative links resolve
• skill names match their directories and follow the Agent Skills specification
• synapseml-pr-loop is 139 lines; synapseml-branches is 57 lines
• no skill line exceeds 120 characters
• readiness snapshot script executed against live PRs
• branch is based on current master
• git diff --check passes

Historical inputs include #2608, #2611, #2617, #2622, #2627, #2631-#2638, and #2644.

Follow-up to #2648.

[github-actions]

Hey Rana Singh (@ranadeepsingh) 👋!
Thank you so much for contributing to our repository 🙌.
Someone from SynapseML Team will be reviewing this pull request soon.

We use semantic commit messages to streamline the release process.
Before your pull request can be merged, you should make sure your first commit and PR title start with a semantic prefix.
This helps us to create release messages and credit you for your hard work!

Examples of commit messages with semantic prefixes:

• fix: Fix LightGBM crashes with empty partitions
• feat: Make HTTP on Spark back-offs configurable
• docs: Update Spark Serving usage
• build: Add codecov support
• perf: improve LightGBM memory usage
• refactor: make python code generation rely on classes
• style: Remove nulls from CNTKModel
• test: Add test coverage for CNTKModel

To test your commit locally, please follow our guild on building from source.
Check out the developer guide for additional guidance on testing your change.

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None

[Copilot]

Pull request overview

This PR refactors AGENTS.md into a shorter, decision-focused agent guide, keeping durable repo-wide rules while pointing readers to authoritative sources for versions, setup, codegen, testing, branch practices, and CI.

Changes:

• Condenses AGENTS.md substantially while preserving key non-negotiable rules and branch-model guidance.
• Replaces version-/example-heavy prose with links to source-of-truth files and repo Skills.
• Keeps a compact repository map and a checklist for Scala-first/codegen conventions and validation steps.

Show a summary per file

File	Description
AGENTS.md	Rewrites the agent guide to be concise and link-driven while retaining core rules, branch model, and validation guidance.

Review details

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

• Files reviewed: 1/1 changed files
• Comments generated: 0
• Review effort level: Lite

[Copilot]

Review details

• Files reviewed: 7/7 changed files
• Comments generated: 1
• Review effort level: Lite

[Copilot]

Review details

• Files reviewed: 7/7 changed files
• Comments generated: 4
• Review effort level: Lite

[Copilot]

Review details

Suppressed comments (3)

Previously missed (2) — in code that hasn't changed since the last review.

.github/skills/synapseml-merge-ready/scripts/Get-PrReadiness.ps1:77

• gh api compare endpoint is built with $view.baseRefName unescaped. If the base branch contains / (common for release/hotfix branches), this produces an invalid REST path and the script will fail even though the PR data is otherwise valid. URL-encode the base ref before constructing the compare URL.

    $compareText = & gh api "repos/$Repo/compare/$($view.baseRefName)...$($view.headRefOid)"

.github/skills/synapseml-merge-ready/scripts/Get-PrReadiness.ps1:97

• Detection of suppressed Copilot review bodies is case-sensitive and requires the exact substring "Suppressed comments". GitHub review templates/messages can vary in casing, which will cause false negatives and silently drop the signal this script is meant to surface. Use a case-insensitive check.

    $suppressed = @($review.reviews.nodes | Where-Object {
        $_.body -and $_.body.Contains("Suppressed comments")
    } | ForEach-Object {

.github/skills/synapseml-merge-ready/scripts/Get-PrReadiness.ps1:7

• The help text claims the script reports "active review threads" and "review bodies containing suppressed comments" without noting that the GraphQL query is capped (reviewThreads(first: 100), comments(first: 20), reviews(last: 50)). For large PRs this can produce incomplete evidence without warning; the help should document these limits (or the script should paginate).

.DESCRIPTION
    Reports head/base state, target divergence, checks, active review threads,
    and review bodies containing suppressed comments. It does not make the
    readiness decision; use the skill's evidence gates for that judgment.

• Files reviewed: 7/7 changed files
• Comments generated: 0 new
• Review effort level: Lite

[Copilot]

Review details

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

.github/skills/synapseml-merge-ready/references/ci-triage.md:28

• Grammar: this reads as though the issue itself has an owner. Consider using “owning issue” to mean the issue that tracks the baseline failure.

Action: collect comparable target/head evidence. Do not silently ignore it; link
the owner issue or repair it when tightly coupled.

• Files reviewed: 7/7 changed files
• Comments generated: 0 new
• Review effort level: Lite

[Copilot]

Review details

• Files reviewed: 7/7 changed files
• Comments generated: 3
• Review effort level: Lite

[Copilot]

Review details

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

.github/skills/synapseml-pr-loop/scripts/Get-PrReadiness.ps1:109

• The loop guard comment says it protects against a cursor that "never advances", but the current check only handles a missing cursor. If the GraphQL API ever returns the same endCursor with hasNextPage=true, this can still loop forever. Capture the previous cursor and also throw when the cursor does not advance.

        # Guard against a cursor that never advances rather than looping forever.
        if ($hasNext -and -not $cursor) {
            throw "$Description reported more pages but returned no cursor for PR #$Number"
        }

• Files reviewed: 7/7 changed files
• Comments generated: 0 new
• Review effort level: Lite

[Copilot]

Review details

• Files reviewed: 13/13 changed files
• Comments generated: 0 new
• Review effort level: Lite

[Rana Singh (ranadeepsingh)]

Final review follow-up on a6eb3fdca7:

• GraphQL errors/missing data now fail explicitly.
• Pagination rejects missing or repeated cursors.
• STALE checks block readiness.
• Single- and multi-PR output always use the same JSON array shape.
• Snapshot content is documented as local/sensitive and must be redacted before sharing.
• The suppressed wording issue now says “tracking issue.”

Validated live against one and two PRs, including complete pagination and stable JSON shape.

[Copilot]

Review details

• Files reviewed: 13/13 changed files
• Comments generated: 0 new
• Review effort level: Lite

[Copilot]

Review details

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

.github/skills/synapseml-pr-loop/scripts/Get-PrReadiness.ps1:31

• $Repo isn’t trimmed before splitting/validation, so inputs like "microsoft/SynapseML " (trailing space) will pass the current owner/name shape check but then fail later with a confusing API error. Trimming early makes the validation actually enforce the intended contract and improves diagnostics.

$repoParts = $Repo.Split("/")
if ($repoParts.Count -ne 2 -or -not $repoParts[0] -or -not $repoParts[1]) {
    throw "Repo must use owner/name format; got '$Repo'."
}

• Files reviewed: 15/15 changed files
• Comments generated: 0 new
• Review effort level: Lite

[Copilot]

Review details

• Files reviewed: 14/14 changed files
• Comments generated: 1
• Review effort level: Lite

[Copilot]

Review details

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

.github/skills/synapseml-pr-loop/SKILL.md:39

• The instruction/link text suggests running scripts/Get-PrReadiness.ps1, but there is no repository-root scripts/Get-PrReadiness.ps1 (the script lives under .github/skills/synapseml-pr-loop/scripts/). As written, readers following the doc from the repo root will get a "file not found" and may assume the readiness tooling is missing.

- Run
  [scripts/Get-PrReadiness.ps1](scripts/Get-PrReadiness.ps1)
  with `-PullRequest <numbers>` and retain its JSON locally as the initial
  snapshot. It can contain review text; redact it before public sharing.

• Files reviewed: 14/14 changed files
• Comments generated: 0 new
• Review effort level: Lite