Prepare public-first contribution documentation

[Brandon Miller (brandom-msft)]

Summary

• prepare the target direct-public contribution path in README.md and CONTRIBUTING.md
• keep prominent transition-draft notices so target behavior cannot be mistaken for the current main behavior
• explain supported-sample validation, exact-commit fork promotion, and the temporary workflow-dependent staging exception
• leave workflows, CODEOWNERS, samples, notebooks, and AI Platform Docs-owned content unchanged

Current verified baseline — 2026-08-07

• Public main is c188cbb30626e99b08be903998b683d8c5fb5dfd; its README and contributing guide still direct sample contributions to private staging.
• Ruleset 6131793 enforces the exact trusted context from GitHub Actions App integration 15368 with 0 approving reviews.
• Legacy private publication workflow 233646160 remains active and is the CURRENT private-to-public publication path. Public mirror workflow 289478915 is retired and reports disabled_manually, with zero queued or in-progress runs.
• public-pr-comment and promote-to-public do not exist.
• Public microsoft-foundry/foundry-samples#895 is OPEN/DRAFT/CLEAN at provisional head 94fe10eb, distinct from private living-documentation microsoft-foundry/foundry-samples-pr#895. Its current code and tests correct the earlier 97564019 blockers, but the artifacts remain absent from public main; there is no independent review, merge, P4 wiring, or pin. The classifier remains TARGET and inert, and its release gate remains unchecked.
• The cross-repo contract is locked but not implemented on main: P5 owns the PUBLIC production manifest at .github/public-transition-manifest.json and PUBLIC matcher at .github/scripts/public_transition_manifest.py, using glob + classification vocabulary. P4 consumes that matcher and owns readiness facts. Private public_pr_transition.py is orchestration only. Public artifacts must land before or atomically with consumers, which fail closed until present. No cadence schedule exists.
  Delegated targets are derived rather than statically inventoried in the manifest: Hosted Agents rules use tracked-sample-yaml-roots; Bicep rules use routing-only rule-root metadata and do not produce dashboard targets. Paths and counts are readiness evidence, not manifest authority.

The canonical CLI is python .github/scripts/public_transition_manifest.py classify --manifest .github/public-transition-manifest.json --paths-file <file> --format json. Matching uses ordered first-match p5-posix-v1 rules with stable IDs, singular glob and classification fields, classification enum internal-only | private-workflow-dependent | public-ready, unmatched default unresolved, and check_class/disposition plus conditional delegation. patterns and category are not contract vocabulary.

Consumers may develop against test-only fixtures but remain fail-closed; after public artifacts land, P4 consumes a public checkout and private orchestration fetches verified public-main blobs. Active private sync continues to block routing.

The current documentation head is provisional, not release-final.

Caution

DO NOT MERGE. Keep this living PR draft and retain both transition notices until all four merge gates are proven against live state. Direct-public behavior remains TARGET and non-current.

Merge gates

1. Public mirror is retired. Public mirror workflow 289478915 reports disabled_manually and no run is active or queued while private sync workflow 233646160 remains active.
2. The helper is inert and fail-closed. The helper, marked-comment entry point, and exact-SHA handler are implemented. Their secretless preflight queries both workflow APIs and rejects unless public mirror workflow 289478915 and private sync workflow 233646160 both report disabled_manually. While private sync remains active, prove command rejection and zero public mutation. Deny internal-only, mixed-classification, and unresolved inputs, and require the exact dependent checks for the requested SHA. The intended output is a public pull request only, never an automatic merge; the inert proof must not perform that public mutation.
3. Private publication sync is retired. Private sync workflow 233646160 reports disabled_manually and no run is active or queued.
4. Public-first routing is operational. Both workflows are disabled, and an exact-SHA end-to-end proof opens an attributed public pull request and never auto-merges. Final direct-public trusted behavior is verified.

During the allowed pre-first-public-merge rollback window, re-enabling either legacy workflow blocks promotion automatically.

The 34 open mirror/public-* pull requests in the private repository remain inert; zero have auto-merge armed, and no backlog pull request was mutated.

Contributor shorthand: private publication sync is retired and public-first routing is operational.

Before merge, remove both Transition draft notices, re-review the final copy against live behavior, and confirm the diff remains limited to README.md and CONTRIBUTING.md.

Coordinated documentation release

Public PR 894 and private PR 895 release as one controlled slice only after both legacy workflows are retired with no active or queued runs, the public production manifest .github/public-transition-manifest.json and matcher .github/scripts/public_transition_manifest.py are approved and proven with glob + classification behavior, P4 readiness-fact integration is proven, private public_pr_transition.py is proven orchestration-only, public artifacts land before or atomically with fail-closed consumers, and marked-comment exact-SHA promotion is proven to open an attributed public pull request and never auto-merge. Record both final documentation SHAs before release. If the private half cannot land after the public half, revert the public documentation immediately; do not leave CURRENT and TARGET guidance split across repositories.

Claim boundaries

This draft says that, after all four gates pass:

• direct public pull requests are the normal contribution path and remain the fallback;
• supported changed samples are detected and validated, with coverage varying by language and sample;
• fork pull requests run credential-free checks but cannot satisfy required trusted validation directly; a maintainer must promote the exact commit to a same-repository branch;
• same-repository documentation-only pull requests satisfy the required check without sample validation;
• temporary staging is used only when a maintainer explicitly directs a workflow-dependent change there;
• promotion is eligible only when both legacy workflows are disabled, creates an attributed public pull request, and never auto-merges;
• an exact manual public pull request is the fallback if temporary promotion fails.

This draft intentionally does not claim fleet health, active cadence, automated refresh, full-repository validation coverage, Rust validation, exercised L4, implemented manifest behavior, private-status reading, quarantine, strike counters, team routing, centralized backlog draining, or bulk mirror-PR closure. It does not recommend forced full exports, marks repair, or replay.

The pinned view in #892 remains the two-row C#/Python presentation surface; missing results are Never run. This unchanged two-row pilot is an integration prerequisite, not final dashboard coverage. After P4.1 lands a finalized producer schema, a separate renderer/config integration slice must consume it, and issue 892 must visibly render real results for the complete derived target set. P4.1 and the full-set dashboard are sample-root-only. The current readiness snapshot is 72 sample rows: 68 public-ready plus 4 Hosted Agents delegated. Bicep rule-root remains canonical metadata for P5/private routing and ADO 5502656, contributes zero P4.1/dashboard rows, and must not create synthetic language, L3, or L4 results. Counts and paths remain re-derived evidence, not manifest authority. PR 893 at a79a438 implements only the dashboard renderer, two-sample configuration, and presentation tests in an open PR. The accepted ownership split assigns manifest consumption, validation orchestration, normalized JSON artifacts, issue-state publishing, schedule, and quarantine to the separate workflow implementation; none of those capabilities is present in PR 893 or operational. Workflow implementation has started but has no reviewed code yet. Any workflow rerun, merge, dispatch, schedule, or quarantine activation remains separately gated. There is no Rust or full-repository validation and no exercised L4 coverage.

Validation

• git diff --check
• changed-file review limited to README.md and CONTRIBUTING.md
• live verification of public main, ruleset 6131793, workflows 233646160 and 289478915, absent promotion entry points, issue 892, and PR 893