docs: document Python quality checkpoints and contributor setup

[Paulo Lacerda (placerda)]

Status and merge dependencies

Documentation companion for #681, coordinated in #689. DRAFT — do not merge or publish. Contributor/operator reconciliation is complete for the immutable component checkpoints below; this does not approve exception proposals, make the full quality gates green, activate repository rules, or establish live integration/recovery acceptance.

Base: docs, from dfa448127a162b86c0836d374b9f2689c61d4ea7 (documented exception to runtime develop). Branch: feature/python-quality-documentation. Final docs head: de1d66d236173c33cac1936a79ed05037baf2d9b. One final reconciliation commit after b81befa, 11 files +413/-48, with the required Copilot co-author trailer. The full PR is 12 existing pages, +670/-4. No new pages or navigation changes.

The three component PRs are dependencies targeting develop: Azure/gpt-rag-orchestrator#346, Azure/gpt-rag-ingestion#296 and Azure/gpt-rag-ui#110. Before merging this PR to the published docs branch, resolve independent component/policy review and adoption, merge the corresponding work through the owning PRs, reconcile any subsequent behavior/interface changes, and obtain separate documentation-publication authorization. Keep all candidate corrections explicitly unmerged until that is satisfied. This PR does not close #681.

Exact component receipts

Component	Immutable checkpoint	Same-head evidence	Remaining quality result
Azure/gpt-rag-orchestrator#346	6b652d8c4d664863a3d02d439b7b77210963320d	34170936566, unit 101890953659: 1880 passed, 8 warnings, 128.90s; frontend 101890953515, typing 101891393211, architecture 101891393219 pass; assets 34170936577 pass	Lint 101891393243: 84 BLE001; exceptions 101891393194: 196 = 98 broad-handler + 98 unused-exception (proposed/unapproved records); policy 101891393235: 1 bootstrap-review. Aggregate 101891539401 fails. 98 proposed, 0 active
Azure/gpt-rag-ingestion#296	f51f5154a0a63df8c7479c14d0b2ddaff93a7f13	34125232907, unit 101752249396: 926 passed, 146 warnings, 26.81s; frontend 101752249345: Node 22.23.2, npm 10.9.8, npm ci 375 packages, 1 test, lint/build pass; typing/architecture pass	60 BLE001 + 130 exception + 10 policy findings; aggregate fails. 65 proposed, 0 active, 0 unproposed
Azure/gpt-rag-ui#110	ee35c9ffea67902b4dc935e287beb5d4640ce6d6	34050677391, unit 101533605342: 521 cases; container 101533605419: 455 behavioral cases, no skips; lint/typing/architecture pass	Exceptions, policy and aggregate fail. 28 proposed, 0 active

Exact job conclusions and behavioral totals were read from GitHub API/logs. The coordinator also confirmed all five final orchestrator quality JSON reports match 6b652d8; their only categories are those listed above, and all 98 exact proposal fixtures executed. Proposed records are not active exemptions. A field named unused-exception here includes the checker's “Stale, proposed or unproven exception” result; it is not a claim that the referenced tests were skipped. No checker exit-0/full-green claim is made. Earlier intermediate unit totals, local warning counts and pending UI-history/MAF-primary claims are superseded by these receipts.

Affected existing pages

Path	Full PR diff	Grounded change
docs/contributing.md	+377/-1	Documentation branch flow; actual Python/Node setup and evidence interfaces; execution trust; typing/module ownership; inactive proposals; accepted UI package/history/asset evidence
docs/governance_audit_contract_v1.md	+10/-0	Boundary-observed completion is not independent proof of primary success; audit best effort is not a primary-failure waiver
docs/howto_authentication.md	+45/-2	Authorization versus success; distinct ingestion/orchestrator configuration outcomes; unexpected required reads; explicitly retained identity-fallback limitations
docs/howto_dashboard_signin.md	+8/-0	Link configuration failure diagnosis to the bounded candidate contract without changing sign-in setup or role gates
docs/howto_grounding_foundry_iq_documents.md	+7/-0	Preserve the fail-closed requirement while distinguishing negative legacy compatibility evidence from permission approval
docs/howto_multimodality.md	+44/-1	Optional ingestion enrichment, primary buffering/error semantics, image-validation outcomes and the unresolved profile-adapter characterization
docs/ingestion_blob_data_source.md	+8/-0	Metadata acquisition failure is not an empty-ACL fallback; SDK confirmations distinguish actual writes
docs/ingestion_nl2sql_data_source.md	+9/-0	Confirmed deletion counts and failed/late scan or purge outcomes
docs/ingestion_sharepoint_source.md	+24/-0	Permission failure, bounded analysis retries, owned task cleanup and truthful partial purge summaries
docs/quickstart_nl2sql.md	+9/-0	Thrown primary failures versus existing typed completed validation/execution answers
docs/services_ingestion.md	+44/-0	Per-document/run/Search distinctions; chunking cancellation; all-page image-reference scan; worker cleanup and truthful purge outcomes
docs/services_orchestrator.md	+85/-0	Streaming/audit boundaries, primary corrections, optional SAS, retained ungrounded answers and bounded managed/hosted persistence behavior

Actual contributor interfaces

Python 3.12; local evidence used 3.12.9 and backend CI also exercised 3.12.14. Development pins are Ruff 0.16.5, mypy 2.3.1, Import Linter 2.14, Grimp 3.16. Install each checkout's actual runtime and quality requirements; unavailable proposal versions are not exercised dependencies. $Base is the fetched protected target SHA, not the candidate SHA.

• Orchestrator: pytest JUnit, then python -I -S .github\scripts\check-quality.py --check all --base-ref $Base --report .artifacts\quality.json --test-results .artifacts\pytest.xml. Its checker/aggregate expose explicit installed wheel paths without site initialization.
• Ingestion: pytest with --junitxml=.artifacts\pytest.xml -o junit_family=legacy; python -I .github\scripts\quality-evidence.py --junit .artifacts\pytest.xml --base-ref $Base --report .artifacts\test-evidence.json; python -I .github\scripts\check-quality.py --check all --base-ref $Base --test-evidence .artifacts\test-evidence.json --report .artifacts\quality.json. Unlike -I -S, -I does not disable all installed site startup.
• Ingestion frontend: from frontend, Node 22 at least 22.12 for Vite 8: npm ci, npm test, npm run lint, npm run build. The integrated React DOM/types, Tailwind 4 PostCSS adapter and existing theme/JSX/Vitest fixes preserve UX. The new frontend-checks job is required by the fail-closed aggregate; this is not an assertion that such a job existed before the candidate.
• UI: requirements then python -m pip install --no-deps -e .; ordinary unittest discovery remains supported. Set QUALITY_RUN_ID once, run python .github\scripts\run-unittest.py --base-ref $Base --report .artifacts\unittest.json, then python .github\scripts\check-quality.py --check all --base-ref $Base --test-evidence .artifacts\unittest.json --report .artifacts\quality.json. The receipt flag belongs to the checker, not the runner.

Preserve source/base/head/run/attempt binding and actual executed results. The three evidence formats are not interchangeable. Static protected evaluator environments are separate from candidate behavioral installation; local virtual environments and interpreter isolation are not OS sandboxes or guarantees against compromised tools. Incremental typing, empty initial backend baselines, stable module identities and exact handler fingerprints remain explicit. Do not self-approve policy changes or treat characterization as approval.

Accepted UI delivery and retained runtime limitations

UI evidence includes 11 installed methods, clean-venv non-editable wheel origins, pip check, copied behavioral tests, synthetic startup/invalid-config cases, Chainlit file persistence/cleanup and separate network-disabled Linux image evidence with a real Uvicorn listener and staged assets. The 12 history-boundary cases and API/service seam are delivered: api/history.py owns the adapter, fresh factory and ambient session/framework operations; services/history.py uses explicit context and the single user cache. Root datalayer exports remain compatible. This is not a Cosmos migration or universally framework-free service rewrite. The accepted UI delivery was not reopened; cross-component/live/recovery acceptance remains separate.

Immutable operator notes distinguish actual corrections from retained compatibility:

• MAF (f06d0cd) and NL2SQL/Multimodal (2dc6928) remove raw ordinary-answer primary failure fallbacks. Existing failed audit/TurnErrorEvent/classic SSE behavior and cancellation remain. Typed SQL result answers remain completed responses; Multimodal model buffering differs from an emitted welcome/partial response. Application-owned safe diagnostics/span evidence is not a global third-party telemetry guarantee.
• Final 6b652d8 retains nullable provider construction that can produce an ordinary ungrounded answer. Foundry client credential failure prevents its retrieve request and HTTP errors omit response bodies, but neither proves every strategy retrieved successfully. Intent failure defaults to question; optional image validation strips images while preserving text.
• 26358cb/0f7b1ce ingestion corrections preserve failed per-document outcomes, bounded service retries and cancellation; failed Blob metadata/SharePoint permission acquisition cannot become empty-ACL indexing. Legitimately empty successful ACL results remain distinct. Purges count confirmed deletions; failed counts/scans/deletes cannot become finished success. All image-reference pages precede deletion; cleanup is attempted, not guaranteed or transactional.
• Ingestion genuine Apply failure remains 500; durable PUT with only best-effort refresh failure remains 200/applied. Orchestrator b93fb58 per-key write failure and post-write refresh failure both remain 500, possibly after durable partial writes, with the bounded field error Unable to persist setting. Actual missing/retry defaults remain; unexpected required configuration reads no longer masquerade as absent/defaulted settings.
• Legacy context-provider/token-setter and API-key environment fallbacks remain inactive compatibility proposals, not strict OBO enforcement, identity approval or permission to query without required user context. MCP-specific guards remain distinct. The normative fail-closed requirement is not weakened.
• Final legacy retry is pre-output, one-shot and preserves input/thread/store=False. Ambiguous managed writes reconcile only the exact two-message tail, never retry the write; hosted remains stateless/no managed operations. Detached Cosmos persistence is not durable-completion assurance. Optional profile extraction has a characterized adapter gap (58c97b6), not an end-to-end success claim or approval of new retention. Optional SAS fallback (ff1bb43) preserves the original URL, not proof of validity/access.

No-change assessment and remaining authorization

Read the parent contracts and documentation-consistency skill and searched affected commands, statuses, runtime owners, failures and defaults. Concrete runtime effects superseded the original blanket operator no-change assessment; only existing relevant pages were changed. The uploader/stream-diagnostic CLI names had no documentation references requiring changes.

Unchanged: docs/deploy.md, docs/hosted_continuity_platform_contract.md, docs/hosted_agent_release_matrix.md, mkdocs.yml, azd/operator startup commands, runtime files, Python pins, configuration keys/defaults, public event/summary schemas, roles and topology. UI still starts with uvicorn main:app --host 0.0.0.0 --port 8080; editable installation is contributor-only. Hosted continuity/panel gates remain off, owner/BFF/OBO distinctions remain, and no settings, deployments, packages or images were published. Parent tasks.md was not edited.

No further component facts are needed for this frozen documentation handoff. Still outside its authorization: individual policy/identity decisions, active exception approval, bootstrap adoption, required-check/CODEOWNERS/bypass settings, clean/negative reference-PR exercises, live peer/Azure/identity integration, production recovery and publication. Parent alone records umbrella task acceptance. Tests or this docs merge must not be used as proxies for those decisions.

Documentation validation

Only existing documentation tooling was used. After the last edit:

python -m mkdocs build --site-dir <session-artifacts>\docs-candidate-site
git diff --check

MkDocs 1.6.1 / Python 3.12.9 completed the final build in 28.06s. The unchanged docs workflow uses Python 3.11. Rendered all 12 affected pages, checked 54 local article links/anchors with zero broken references, and confirmed the three final immutable contributor revisions. Only the pre-existing INFO for orchestrator_visual_guide.md outside navigation remains. No new dependencies/tools, component-suite reruns, publishing workflow or mkdocs gh-deploy were used.

Final docs SHA/build receipt and affected paths are handed to the coordinator and recorded on #689. This replaces the earlier three-page/intermediate-SHA handoff; it does not assert a release or full quality acceptance.

[Paulo Lacerda (placerda)]

Ingestion contributor interface is now stable in draft Azure/gpt-rag-ingestion#296, head bbe52923dbaf2b8ce4f6f371e492ad32ae7ffe45, target develop. Please keep publication/activation gated. See its docs/python-quality.md and PR body for the exact commands and ownership map.

Python 3.12.9; Ruff 0.16.5 / mypy 2.3.1 / Import Linter 2.14 / Grimp 3.16. Install requirements-quality.txt; run python .github/scripts/check-quality.py --check all --base-ref <protected-sha> --report .artifacts/quality.json. Optional --test-evidence takes same-candidate pytest node evidence; --repository is for base-side evaluation. Exit 0 pass / 1 violations / 2 error. Typing blocks audit_contract, audit_sanitizer and new jobs.runtime; independently discovered new modules become blocking. Individual multiset diagnostic identity, no count baseline/no global missing-import ignore. Zero baseline and exception records. 295 maintained tests passed at committed SHA, architecture passed, but 218 unapproved handlers and 131 Ruff findings keep this a draft. Required-check activation and live/recovery acceptance are not claimed. The plan's unavailable candidate pins are documented as a deviation, not represented as tested.

[Paulo Lacerda (placerda)]

Orchestrator contributor facts are stable in Azure/gpt-rag-orchestrator#346 (draft to develop), ef649eeab6144156b4c90c4422d62f229454dedc. Python 3.12.9; requirements-quality.txt pins Ruff 0.16.5, mypy 2.3.1, Import Linter 2.14, Grimp 3.16. CLI: python .github/scripts/check-quality.py --check all --base-ref --report .artifacts/quality.json --test-results .artifacts/pytest.xml. Produce evidence via python -m pytest -q --junitxml=.artifacts/pytest.xml (840 passed). Type scope: four planned seed modules plus connectors.obo, 5/78 modules, zero baseline entries; new modules join scope, imported uncovered errors remain visible. Full graph green; no exception exemptions approved: 154 broad handlers / 100 BLE001 findings are blocking, as is missing protected bootstrap policy. AGENTS.md supplies exact setup/ownership/activation guidance. Gate documentation must remain proposed, not active. Maintainer review, strict-policy follow-up and live/admin acceptance remain outstanding; see draft PR for all evidence and compatibility refs.

[Paulo Lacerda (placerda)]

UI checkpoint is now Azure/gpt-rag-ui#110, an open draft targeting develop, at 4959ecaf04ea94ce0d35837c73b43ea3884c5be8; base c635bc6696714b543feec24b4a062a8a8f3ff6d0. This supersedes the earlier implementation-only ce76b00 checkpoint. The PR body carries the complete command/result/task/remaining-work handoff.

All 32 researched inventory entries have canonical package owners; this is not merely a skeleton. config/util, auth/clients, services, api/telemetry and bootstrap contain the implementations. Legacy root/connector modules are thin adapters; citations are service-owned and the app/history cycle is removed. Shared state and callback registration retain one canonical owner. Existing history still inherits Chainlit BaseDataLayer, and citation configuration is service-owned rather than fully context-injected; final contract review remains explicit.

Contributor commands:

python -m pip install -r requirements.txt
python -m pip install -r requirements-quality.txt
python -m pip install --no-deps -e .
python -m unittest discover -s tests -v
uvicorn main:app --host 0.0.0.0 --port 8080

Non-editable install: python -m pip install --no-deps ., or python -m pip wheel --no-deps --wheel-dir .artifacts/wheel . followed by installation of that wheel. Runtime dependencies remain exclusively in requirements.txt. Docker retains /app and uvicorn main:app; it adds non-editable package installation.

The artifact is code plus externally staged .chainlit, public, chainlit.config.yaml, chainlit.md, VERSION, not writable assets in site-packages. Existing CHAINLIT_APP_ROOT, an applicable source-adjacent root, or cwd resolves the resource root before Chainlit imports.

Evidence: 410 original/migrated tests passed; final complete suite passed 436 tests, including 17 quality, 3 legacy compatibility and 6 installed-package tests. Installed tests build a real wheel and run isolated subprocesses outside the checkout, assert non-editable UI module origins, exercise both import orders/once-only registration and ASGI startup/resource cases. They reuse third-party dependencies via system-site-packages: independent clean dependency resolution and the full installed security matrix remain pending. Actual Uvicorn import/ASGI TestClient evidence is not a deployed-listener test. Agent asset validation passed. Full-suite checkpoint was 34273ff; final 4959eca only changes documentation line endings and two EOF blank lines.

Quality CLI:

python .github/scripts/check-quality.py --check all --base-ref c635bc6696714b543feec24b4a062a8a8f3ff6d0 --report .artifacts/quality.json

Actual pins: Ruff 0.16.5, mypy 2.3.1, Import Linter 2.14, Grimp 3.16, setuptools 80.9.0. Research's higher Ruff/Import Linter/Grimp pins were unavailable. Blocking typing covers canonical config.chat_backend, config.panel_config, config.hosted_continuity_config, new modules and legacy adapters; moved legacy owners keep stable IDs/prior uncovered status. Typing baseline and approved exceptions are both empty. 119 imported legacy type diagnostics remain visible, not full-repository typing success.

At final head: typing and architecture pass; lint has 20 BLE001 findings, exceptions have 62 unapproved inherited handlers, policy has 1 bootstrap-review finding; combined exit 1. Do not document completed/activated quality adoption. Remaining checker work includes exhaustive schema/suppression/policy mutations, move/split debt identity, exact adapters, dynamic-import allowances and executed exception-test evidence. Real required-check/latest-head enforcement is not established.

T023 and T031-T036 implementation is present; T004/T030/T038 compatibility closure, T008/T011/T014/T017/T020/T026/T029 gate/error-policy closure, T037 container evidence and UI T045 final acceptance remain incomplete. T041 ownership/install/rollback guidance is in the PR and docs/python-development.md; parent/docs reconciliation should retain these limitations.

Linux container execution is blocked by the unavailable Docker Desktop Linux daemon. Live exact-peer integration (orchestrator v4.1.1, ingestion v2.7.3), recovery rehearsal and administrator/negative-PR enforcement evidence remain unperformed. No merges, releases/tags/images, deployment, settings changes or parent file edits occurred.

Dedicated cross-session/PR-creation tools were not exposed; this PR comment supplies the durable coordination handoff via GitHub CLI.

[Paulo Lacerda (placerda)]

T041 correction: ce76b00 was the implementation-only commit. The contributor/AGENTS update landed in 34273fffb1da549252e82ed0337e3cdd22636042 and is included in the current Azure/gpt-rag-ui#110 draft head 4959ecaf04ea94ce0d35837c73b43ea3884c5be8, targeting develop.

Use these immutable final-checkpoint references:

• AGENTS canonical ownership and legacy adapter map.
• AGENTS contributor installation and quality commands: includes python -m pip install --no-deps -e . after runtime/quality requirements.
• Developer installation, ownership, staged assets and explicit limitations.

Confirmed UI CLI has only --check, --base-ref, --report (plus help); do not copy backend evidence flags.

Please distinguish completed local installed-wheel evidence from pending acceptance: six non-editable wheel/import/resource tests passed inside the 436-test local suite. Independent clean dependency resolution, the full installed security/configuration matrix, Linux container parity and CI/administrative acceptance remain unproven; the quality proposal remains red/incomplete. The PR body and previous coordination comment provide exact commands/results and scope. No further source changes or checkpoint expansion are needed for this documentation correction.

[Paulo Lacerda (placerda)]

Orchestrator follow-up facts for Azure/gpt-rag-orchestrator#346: head 4e7fdcad98af6e217d37d4d7fa6f3a314a3d91ca, 874 tests passed, pins/CLI unchanged. Five exact audit exception records are proposed and source/test-bound; zero are active. 154 broad sites / 100 BLE001 findings and bootstrap review remain blocking. Strict parsing and dynamic/member resolution now have expanded negative cases. The stronger resolver uncovered and repaired a stale AzureOpenAIClient import in the legacy retrieval plugin; it reuses get_genai_client and awaits embeddings, preserving the security filter/error envelope. I searched published docs/contributing.md, services_orchestrator.md, howto_retrieval_optimization.md and orchestrator_visual_guide.md for old/new connector/plugin names: no affected operator references. AGENTS and Unreleased changelog updated. Please keep gate claims proposed; current CI failures are not an active or completed enforcement rollout.

[Paulo Lacerda (placerda)]

Latest orchestrator evidence update: Azure/gpt-rag-orchestrator#346 at 29df99d9b1e1393d6b775d9d5362c445a7fdd021. 884 tests pass, including 117 policy fixtures; 10 exact audit recovery/propagation records are proposed, 0 active. Pins/CLI/type scope/zero baseline unchanged. All 154 broad sites remain unapproved (144 non-audit sites still need individual disposition); 100 BLE001 and bootstrap policy remain blocking. Proposed CODEOWNERS now uses two verified existing admins, placerda and gxjorge; settings are still untouched. Keep publication gated and do not infer completed enforcement from the passing behavioral suite.

[Paulo Lacerda (placerda)]

Ingestion documentation follow-up for Azure/gpt-rag-ingestion#296 is committed at 46d08d31e5090045e481f22da699e09f444159dc, still draft/develop. Please reconcile published ingestion/operator/audit guidance with these explicit bug-fix semantics: Search deletion uses SDK delete and confirmed matching counts; NL2SQL failed scans/partial deletion propagate; missing/malformed/duplicate Search results cannot emit positive audit events; governance provider failure no longer silently disables governance; config apply returns 500 on failed scheduling; remote config writes followed by failed local refresh use existing 207 partial-failure responses. Selected write/refresh/reschedule/manual scheduling diagnostics omit exception payloads. Successful API shapes, auth, labels, schema bytes and shipped peer versions are unchanged. Cron/manual failures propagate; ordered independent startup jobs still continue after one fails; audit side effects remain best-effort.

AGENTS/README/Unreleased/docs/python-quality.md and the component PR describe this. Gate remains incomplete: 348 tests pass, typing 3 modules/0 baseline entries, full graph no findings, but 202 unapproved handlers + 131 BLE001 + 4 proposed-record findings + 9 policy findings block acceptance. Four exact audit proposals, zero active approvals; proposed records cannot waive lint/exception checks. An exact active protected record may waive only its BLE001 header, with separate required same-run failure evidence. No activated enforcement/live validation claim. Parent #689 has the full follow-up handoff and owns published coordination.

[Paulo Lacerda (placerda)]

Stable orchestrator tooling repair: Azure/gpt-rag-orchestrator#346, exact SHA 550a6eedc022c879658964cbac919835c6d3b96d. Contributor dependency/test/check-quality commands and pins unchanged: Python 3.12.9; Ruff 0.16.5, mypy 2.3.1, Import Linter 2.14, Grimp 3.16 (development only). 185 quality fixtures / 952 suite tests pass. Important clarification for contributor page: new modules stay blocking relative to the protected adoption inventory, not only their first PR; imported uncovered diagnostics remain visible/nonblocking under accepted incremental scope. Source policy catches typing.no_type_check and aliases; malformed mypy JSON is an analysis error. Report schema v2 binds protected policy/toolchain, repo/base/head and CI run/attempt; aggregate independently validates from exact protected base, and earlier-attempt reports fail (rerun all quality jobs together). Local check-quality CLI unchanged, internal aggregate additionally takes --repository --run-id --run-attempt. Counts unchanged: 5/78 blocking, 73 uncovered, zero debt, 154 broad sites, 10 proposed/0 active; lint/exceptions/bootstrap and overall gate remain red. PR body has exact commands/results. No settings or publication authority implied.

[Paulo Lacerda (placerda)]

Scoped quality follow-up delivered

Azure/gpt-rag-ui#110 remains a draft targeting develop, at ae9d0d7d41556e0d8d4c4116fbb17765fbc1210f. This closes the requested quality-tooling follow-up, not overall quality adoption or administrator/live-environment acceptance.

Child commits:

• ab523d84dde80e4c62bdf2c6cd7cdf52f5a50ad0: schema/source/evidence/aggregation hardening and the explicitly reassigned Linux container helper/job.
• ae9d0d7d41556e0d8d4c4116fbb17765fbc1210f: additional parent-reviewed lexical alias, package initializer, next-PR typing coverage and malformed-diagnostic fixes.

Parent commits 043d89b87bd2504a9df1429df35c4ed05b4c2d60 and e9620fce81daa879c0d945113911e58ae4b574e3 were preserved. I did not edit or stage runtime modules, packaging metadata, test_installed_package.py, test_module_compatibility.py or .dockerignore. The working tree is clean. Both child commits include the required co-author trailer.

Delivered enforcement

• Closed four-record schemas reject missing/unknown fields, duplicate JSON keys/IDs/sites, invalid versions/dates/types/paths, unknown scope references and duplicate move destinations.
• Protected coverage retains stable identities, automatically types new modules and requires those additions to be persisted before merge, preventing coverage loss in the next PR. Unchanged one-to-one moves retain identity; ambiguous/changed moves and splits need explicit protected allocation. Debt retirement works without permitting growth, duplication or revival.
• Qualified signatures cover class/nested functions, overload occurrences, variadic arguments, variables, decorators and module-level type aliases. Suppressions are syntax-site-bound rather than count-only. Lexical import aliases cannot be overwritten by unrelated functions; package-relative resolution honors inventoried __init__.py ownership.
• Exact adapter imports, export targets, call/order fingerprints and declared facade chains must terminate at real canonical exports. Current runtime adapters pass; no runtime repair was made.
• Dynamic loaders include literal keyword/alias forms. Variable sites need exact function/context fingerprints, nonempty permitted targets and executed behavior tests; a record cannot cover a second function with an identical call.
• Handler fingerprints bind the protected operation, catch/outcome and distinct occurrence. Active protected records require exact source/types, date/stage validity and same-run, non-skipped passing tests. No approvals were fabricated; contractual best-effort outcomes remain representable.
• Standard unittest execution receipts bind test method/source/outcome, candidate/base/source digest and run ID/attempt. Unknown mypy severities/malformed diagnostics fail execution. Protected aggregation checks actual job results and independently expected Git/source/run/tool values, rejecting even coordinated, resealed artifact forgeries.

The supplementary inventory has 63 sites. The previous checker reported 62 because two separate handlers in AppConfigClient.__init__ had identical handler-body fingerprints and collapsed into one dictionary entry. The new count is not a new runtime handler.

Commands and evidence

At final head, local focused execution:

$env:QUALITY_RUN_ID = [guid]::NewGuid().ToString()
.\.venv\Scripts\python.exe .github\scripts\run-unittest.py --base-ref c635bc6696714b543feec24b4a062a8a8f3ff6d0 --pattern test_quality_policy.py --report .artifacts\quality-receipt-ae9d0d7.json
.\.venv\Scripts\python.exe .github\scripts\check-quality.py --check all --base-ref c635bc6696714b543feec24b4a062a8a8f3ff6d0 --test-evidence .artifacts\quality-receipt-ae9d0d7.json --report .artifacts\quality-ae9d0d7.json

37 focused unittest tests passed in 37.037 seconds. These include real disposable Git repositories and unittest/aggregate subprocesses, not solely mocked success reports. New negative fixtures were run before fixes: the initial batch reproduced 13 failures/eight errors; the additional cross-cutting batch reproduced three failures/one missing-parser error. Dynamic alias/keyword cases were separately demonstrated failing before repair.

The final actual quality CLI exits 1:

Check	Result
lint	20 inherited BLE001 violations
typing	Passed, zero blocking findings
architecture	Passed, zero graph/private/adapter findings
exceptions	63 unapproved inherited sites
policy	One missing-protected-base bootstrap-review violation

Typing baseline and approved exception entries remain empty. Tool pins remain Ruff 0.16.5, mypy 2.3.1, Import Linter 2.14, Grimp 3.16; setuptools remains 80.9.0. Scoped Ruff checks and the existing agent-asset validator passed.

Actual Linux CI, not a missing-daemon assumption

Final-head run: https://github.com/Azure/gpt-rag-ui/actions/runs/34043024295

unit-tests, container-tests, typing and architecture succeeded. lint, exceptions, policy and quality-gate failed as expected from the outstanding violations above. This is real final-head CI evidence, not a pending or simulated Linux result.

The child-owned tests/container_smoke.py is outside normal test discovery. CI builds the existing Dockerfile into an ephemeral image, mounts the tests read-only and runs the helper with --network none. It verifies installed canonical origins, staged assets, original main:app Uvicorn listeners (ready and disconnected-not-ready) and all 410 existing behavioral cases without skips. Dependencies/images download only during the build; no image is pushed or deployed. Local helper validation also passed both listeners and 410 cases against a non-editable wheel; that local harness reused third-party dependencies and is separate from the parent's clean-environment proof.

The parent's installed tests now use clean dependencies and pip check, not system-site-packages; its ten-method coverage includes copied behavioral tests, real Entra/Copilot startup/auth order and upload write/cleanup cases. The previous installed-environment limitation is retired, not hidden.

Handoff and remaining acceptance

UI CLI now adds --test-evidence to --check, --base-ref and --report. The separate unittest runner supports --pattern for focused work; CI aggregation requires complete test_*.py discovery. CI supplies run ID/attempt automatically; local receipt commands set QUALITY_RUN_ID once. The required real jobs now include container-tests. Contributor/AGENTS guidance documents these controls and their limits; hashes are integrity checks, not authentication or substitutes for protected execution and actual job outcomes.

This advances T008/T011/T014/T017/T020/T026 and quality T041/T045; T037 now has actual Linux image/runtime evidence. Parent retains runtime/package/U4 closure and FR-008 handler decisions. Remaining adoption work is classification/narrowing or genuine exact approval of the inherited handlers, the bootstrap/protected-policy review route, administrator/latest-head/negative-PR enforcement evidence and unavailable live exact-peer integration/recovery. No all-fallbacks-forbidden rule, blanket ledger or self-approval was introduced.

No merge, tag/release/image publication, deployment, settings change or parent repository file edit occurred. Pausing this scoped turn at the committed, verified handoff.

[Paulo Lacerda (placerda)]

Orchestrator draft Azure/gpt-rag-orchestrator#346 now at 8d0ac0532b06b2fe83a084d5748646c3009c7283. Contributor CLI and Python/tool pins unchanged. Current counts: 978 tests, 190 quality fixtures; 5/78 blocking, zero baseline; 153 broad sites, 11 proposed (10 audit+1 turn), zero active. JUnit class selectors resolve to real source modules and duplicate/unknown evidence is rejected. Quality remains red: lint99, exceptions164, bootstrap1. Source-backed provider→startup/strategy and real MafLite→turn→HTTP SSE characterization now documents the legacy raw-error text/logging and success-shaped audit outcome risk; do NOT describe all strategies as safely propagating errors or these tests as confidentiality acceptance. Only runtime change in this latest batch removes the unnecessary host-formatting broad catch after getenv string/missing checks. All other fallback/error contracts remain unchanged. PR body has exact commands and residual acceptance; no settings activation or live validation performed.

[Paulo Lacerda (placerda)]

Final orchestrator scoped freeze confirmed at Azure/gpt-rag-orchestrator#346 head 8d0ac0532b06b2fe83a084d5748646c3009c7283, clean tree, draft/develop. Immutable-head rerun: 978 pass, 7 existing warnings; 190 quality cases; exact-head CI Python/frontend/typing/architecture pass. Current 153 broad/11 proposed/0 active; 142 unproposed. Contributor CLI/pins unchanged. Clarification for 93e4d5c: --test-results still consumes pytest --junitxml output; resolver now maps classname to an existing test module followed by ::Class::test, rejects unknown modules/duplicate selectors, excludes failed/error/skipped evidence. --root is respected internally. JUnit itself is not signed or an approval; provenance comes from protected execution/actual needs/same-workflow artifact download and report-v2 run/attempt checks. Final PR body now explicitly says recovery to v4.1.1 is unexercised and does not restore subsequent conversation data, persisted config or administrative settings. Seven original reviewer findings closed independently at 550a6ee; overall adoption, raw-error/MAF semantics, genuine approvals, activation and live compatibility/recovery remain open. No publication/settings change.

[Paulo Lacerda (placerda)]

Compatibility correction from the immutable ingestion assessment: the pending follow-up restores PUT /api/config durable-write success (200/applied) even when its PRE-EXISTING best-effort local refresh fails; do not publish the earlier proposed 207 behavior for that case. /config/apply 200-to-500 for genuine application failure and worker/provider exception propagation are observable contract-restoring changes, not identical failure semantics. Selected-provider read failures propagate while real missing-key defaults, env opt-in, bootstrap fallbacks and selector order remain. Eight proposed records, zero active. Purge cleanup and pinned SDK/audit independence evidence are being finalized. Recovery must explicitly state that code rollback does not recreate deleted Search documents or undo persisted config; /ingest-documents direct upload is outside wrapper proof. Component README/contributor/changelog guidance is updated locally; exact runtime follow-up SHA will follow.

[Paulo Lacerda (placerda)]

Frozen final UI checkpoint: Azure/gpt-rag-ui#110, draft to develop, head 871106dbe891a1ccde373b4964c5e56a71c4f4cc. Working tree is clean. The updated PR body contains the three-repair fixture mapping, exact commands, changed surfaces and remaining acceptance. No further implementation is underway.

Counts: 48 focused quality tests pass. Final CI https://github.com/Azure/gpt-rag-ui/actions/runs/34045788683 passed 471 unit tests, typing and architecture; offline Linux acceptance passed both real main:app listener states and 410 behavioral cases. Adoption remains red: 20 lint /63 unapproved handlers /1 bootstrap-policy finding, with quality-gate correctly failing. Baseline and approved exception entries remain empty.

CLI unchanged: check-quality.py --check all --base-ref <protected-base-sha> --test-evidence <unittest-receipt> --report <quality-report>. The separate standard-unittest runner retains --pattern; local evidence sets QUALITY_RUN_ID once, CI uses run ID/attempt. No new tools or pins; mypy-only explicit bases are src and ..

All three parent repros are now independently confirmed fixed at the immutable head. Runtime and parent-owned files were preserved. U1's bounded Chainlit/history seam remains pending under parent ownership; no DTO/storage redesign, approval fabrication, merge, publication, deployment or settings change occurred. Paused for the single docs/umbrella reconciliation.

[Paulo Lacerda (placerda)]

Final ingestion docs pin: Azure/gpt-rag-ingestion#296 at 3a46472b19049631fa4427699a79968134a46769, frozen clean draft/develop. Parent #689 and the rewritten component body contain the consolidated exact commands/task/recovery evidence.

Use current counts: local/CI 422 passed, checker subset116, bounded SDK/runtime subset60; graph53/145 (Grimp41), typing3 blocking/0 baseline/0 in-scope and344 imported local diagnostics. Eight proposed, zero active exceptions. Full gate exits1 with350 findings (202 handlers +131 BLE001 +8 pending +9 policy); CI unit/typing/architecture/assets pass, aggregate fails for those violations. Current CI34046006654 has no remaining unit fixture failure. All five original tooling findings independently closed.

Publish PUT200/applied retained after successful durable write + failed best-effort local refresh, not the superseded207 claim. Genuine /config/apply200-to-500 failures and worker/provider propagation are observable contract-restoring changes, not unchanged error semantics. Real provider2.5.0 preserves selector order and last-selected duplicate precedence; Search11.5.2 models are deserialized; prior ambient2.1/11.7 evidence is superseded, with no runtime pin change. Audit remains best-effort; cleanup warnings cannot replace a primary failure or invalidate confirmed work.

Direct /ingest-documents remains outside wrapper failure proofs. Rollback cannot restore deleted Search documents or undo persisted configuration; those need separately authorized data/config recovery. Shipped peers remain orchestrator4.1.1 andUI2.6.2; no schema/audit bytes, credentials, labels, VERSION or frontend workflow changes. No merge/publish/deploy/settings changes. This is the final handoff for your consolidated docs/umbrella commit, not green quality adoption.

[Paulo Lacerda (placerda)]

Atualizacao CLI estabilizada no milestone orch 703e67f94f4f36971bdb388e0eacb920560f9b6e (draft Azure/gpt-rag-orchestrator#346/develop): checker agora exige python -I -S .github\scripts\check-quality.py --check all --base-ref $Base --report .artifacts\quality.json --test-results .artifacts\pytest.xml. Mesmo -I -S no aggregate. Demais comandos de dependencias/pytest inalterados; Python3.12.9, Ruff0.16.5, mypy2.3.1, ImportLinter2.14, Grimp3.16. Ferramentas analisam snapshot fonte sem import de runtime, startup hooks desativados, caches novos e configs executaveis rejeitadas. CI quality usa deps runtime da base protegida; testes seguem deps candidatas em job separado. 201 casos tooling passaram; lint/exceptions/adocao ainda nao verdes. Zero aprovacoes ativas/zero divida typing; imported-outscope continua visivel nao bloqueante. Nao publicar como gate ativado. Revisao T006 ModuleSurface e correcoes runtime continuam; parent assumiu MAF.

[Paulo Lacerda (placerda)]

Contributor metadata refinement stable at orchestrator61b26e4c829c4c2ca81b46926a248cd317a87961 (draft Azure/gpt-rag-orchestrator#346): .quality/module-surfaces.json now holds complete78 ModuleSurface records/all11 planned fields. policy.modules remains immutable adoption names so new modules cannot later become uncovered. Full surface file joins protected digest/review; consumers/exports/provenance and stable move identity are enforced. 5 explicit blocking seeds, empty debt, 0active approvals unchanged. CLI/pins unchanged from703e67: Python3.12.9; Ruff0.16.5/mypy2.3.1/ImportLinter2.14/Grimp3.16; python -I -S .github/scripts/check-quality.py --check all --base-ref --report .artifacts/quality.json --test-results .artifacts/pytest.xml. Fresh JUnit is required for exceptions. Quality fixture suite228passed. Parent currently owns an uncommitted MAF correction, so final runtime behavior/docs SHA still pending; do not publish characterization as approved behavior.

[Paulo Lacerda (placerda)]

Runtime documentation update now stable at orchestrator f06d0cd7204c63e61ce1b6c80ae768c5f7f0597c (draft Azure/gpt-rag-orchestrator#346): MafLite and MAF Agent Service failures now use existing generic typed error/SSE channel, never raw exception text as ordinary answer. Audit rejects/fails the request instead of successful completion; cancellation remains distinct; existing frame/schema/headers and finally persistence preserved. Enclosing stream_response SDK span disables automatic exception capture and has constant internal_error status; SSE log is constant. This does NOT promise all provider telemetry sanitized. Parent authored bounded runtime correction; own rerun220passing confirms relevant strategies/hosted/history/audit/schema.13 exact exception proposals/0active now; adoption gate still red. Dependencies/tool pins/isolated CLI unchanged. Final full-suite SHA remains pending remaining parser work.

[Paulo Lacerda (placerda)]

Stable parser/runtime milestone:5883d0a4abdd98146b53d2c4858ccf971d707655 on draft Azure/gpt-rag-orchestrator#346 (develop). Full1071passed/7warnings; frontend passed. Tool CLI unchanged from isolated703e67f: python -I -S .github\scripts\check-quality.py --check all --base-ref origin/develop --report .artifacts\quality.json --test-results .artifacts\pytest.xml. Use pytest -q --junitxml=.artifacts\pytest.xml first. Python3.12.9; Ruff0.16.5/mypy2.3.1/ImportLinter2.14/Grimp3.16.78surface records,5blocking/73uncovered; baseline0;142broad sites/13proposed/0active/129unproposed. Lint91,typing0,architecture0,exceptions155,policy bootstrap1. Beyond prior safe MAF outcome: malformed parsing retains recovery, unexpected parser failures propagate; actual Tenacity callback repaired so existing5attempt retry budget works before optional default/required-setting failure. No config key/default change. Remaining legacy diagnostics/fallbacks not certified. PR body now replaces obsolete frozen/rawMAF/isolation-unverified claims. Local passing source evidence is distinct from pending exact-head CI; no admin/live acceptance or publication.

[Paulo Lacerda (placerda)]

Stable pushed orchestrator receipt: f3cf4d60470867647bedf650b4a716fcf0d7f7ef, draft Azure/gpt-rag-orchestrator#346/develop. Local full1102 pass; isolated all lint89/typing0/architecture0/exceptions150/policy1,135 broad/15 proposed/0 active/120 unproposed,5/78 blocking/0 debt. Exact Linux CI34060247333 completed: tests/frontend/typing/architecture passed; lint/exceptions/policy/aggregate failed; assets34060247323 passed. SQL/Fabric driver/Azure exceptions now narrow with unchanged propagation/credential cleanup; optional converter ImportError-only; nested provider RetryError retried; bounded AppConfig/Search logs; redundant inner audit catches removed. Contributor CLI/pins unchanged: Python3.12.9, Ruff0.16.5/mypy2.3.1/Import Linter2.14/Grimp3.16, checker must use -I -S and --test-results JUnit. Documentation must retain draft/adoption/approval/admin/live limitations. Parent now owns a disjoint blob_sas batch; I am closing exact hosted transport/MCP cleanup evidence, not altering wire contracts or reauditing isolation. Final head will follow.

[Paulo Lacerda (placerda)]

Docs stable orchestrator head now acaefa49e46735dd506750fd442b87077d29f200 (draft Azure/gpt-rag-orchestrator#346). Full1217pass/7warnings;239qualitycases; lint83/typing0/architecture0/exceptions146/policy1;124broad/22proposed/0active/102unproposed;5/78blocking/0debt. CLI/pins unchanged. Latest behavior: typed Cosmos SDK failures preserve existing unavailable results and SDK-read404/API-mutation500; unexpected programming errors now propagate to generic500 instead of being mislabeled missing, cancellation/principal guards unchanged. Four exact HTTP proposals and bounded diagnostic logs. Telemetry optional settings use allow_none; defaults/env precedence/unavailability retained, callback bugs surfaced, HTTP setting read once. Search token failures never issue a request and propagate unchanged. No persistence migration or claim of rollback after failed writes. Current PR body has exact commands/results/recovery/remaining gaps; parent blob-signing work not yet included. Linux756 receipt1116pass/8warnings/Python3.12.14; currentaca CI separate.

[Paulo Lacerda (placerda)]

Stable head2be12230003c140ed3fcd3204ea73e6afbb25661 now has exact Linux receipt34062040196:1239passed/8warnings/36.22s; frontend/typing/architecture/assets passed; lint/exceptions/policy/aggregate red as documented. Local prior full1217, current auth/consumer106 and exact-record/auth33 pass. Current inventory122broad/23proposed/0active/99unproposed;240qualitycases; lint81/typing0/architecture0/exceptions145/policy1;5/78blocking/0debt. Pins and -I -S/JUnit CLI unchanged. JWT parser/verifier narrowing preserves actual signed v1/v2, rotation/alternate JWKS, role/issuer/audience/tenant checks, required-setting500 and cancellation; unexpected provider/verifier failures still deny401 with bounded class-only diagnostics. No auth/cache policy change. Draft Azure/gpt-rag-orchestrator#346 body now includes exact source/task/command/CI/recovery accounting, pending legacy NL2SQL+multimodal thrown-failure disposition and outstanding parent blob-signing delegation. No global confidentiality/adoption/required-settings/live-recovery claim.

[Paulo Lacerda (placerda)]

Orchestrator docs update: draft Azure/gpt-rag-orchestrator#346 head b93fb58cdb59dbb30b1db88b39c8843296b7713b now integrates signing, grounded NL2SQL/multimodal primary propagation, typed SQL/retrieval result boundaries, Key Vault/OpenAI narrowing and returned HTTP/auth/default/partial-write dispositions. PR body has current contributor CLI (static checker still python -I -S), JUnit semantics, fixed pins/Python, exact milestone commands and recovery limitations. Current inventory112 broad/51 proposed/0 active/61 unproposed; not final adoption. No active approvals/settings/publication. Latest fully collected predecessor CI67ed1a9:1452 passed/8warnings, Python3.12.14; current HTTP integration497 passed locally (Python3.12.9). SchemaInfo nullable-columns/no serialized error-field limitation remains. Unsupported structured-output formats retain explicit bounded warnings, while unexpected schema-hook failures prevent model access. Dashboard partial writes/refresh failures remain500 without rollback. Published docs remain gated on final coordinated heads; no change to tool pins or shipped peer compatibility.

[Paulo Lacerda (placerda)]

Orchestrator operational doc delta at049754b: src/upload_prompts.py and src/util/test_stream.py now report failures via nonzero exits. Uploader still uses cwd/prompts, preserves confirmed partial writes, continues after known read/unconfirmed-write failures, then exits1; missing directory fails before Azure initialization. Stream diagnostic preserves partial chunks and cleanup, exits1 for HTTP/transport failure and omits non-success response bodies from stdout. Unexpected errors/cancellation propagate. AGENTS updated; repo search found no README/scripts references to these helpers. Please include only if an affected published contributor/operator page documents them; no new setting or runtime/API/SSE/data migration. Exact proposal review and required-check activation remain unapproved.

[Paulo Lacerda (placerda)]

Final runtime/source closure integrated locally: own11 and returned parent11 inactive proposals plus2 redundant wrapper removals; expected inventory98 broad/98 proposed/0 active/0 unproposed, pending final source-ledger check. Own selection625 passed, legacy replay127 passed; consolidated full suite/frontend now running. Contributor commands and pins unchanged (Python3.12.9; Ruff0.16.5/mypy2.3.1/ImportLinter2.14/Grimp3.16; quality uses python -I -S). Will send immutable final SHA and same-head CI receipt before your final docs build. Preserve limitations: ungrounded answers after nullable provider construction, legacy token/search-context continuation, non-MCP forced anonymous/header-removing retry and API-key env fallback are NOT newly approved/strict OBO. Foundry HTTP errors now status-only/no provider bodies; MCP credential/request errors and legacy propagation distinct. Optional memory chat_options/options/value interop gap retained, not accepted extraction feature. Detached persistence and per-key partial writes are not durable-completion/rollback guarantees.

[Paulo Lacerda (placerda)]

FINAL IMMUTABLE ORCHESTRATOR RECEIPT for docs/parent: Azure/gpt-rag-orchestrator#346, feature/python-module-boundaries -> develop, source SHA6b652d8c4d664863a3d02d439b7b77210963320d. Code closure complete, no outstanding source ownership. Exact inventory98 broad/98 proposed/0 active/0 unproposed/0 stale;5/78 blocking typing,73 outside scope;0 debt,0 cycle baseline;55 visible nonblocking imported type diagnostics locally. No active approval.

Same-head CI https://github.com/Azure/gpt-rag-orchestrator/actions/runs/34170936566 attempt1 COMPLETED: tests job101890953659=1880 passed/8 warnings/128.90s, Python3.12.14; frontend101890953515 PASS; typing101891393211 PASS/0 findings; architecture101891393219 PASS/0. Assets34170936577/job101890953696 PASS. Actual expected adoption failures: lint101891393243=84 BLE001; exceptions101891393194=196(98 unapproved broad+98 inactive-unused records); policy101891393235=1 bootstrap-review; aggregate101891539401 FAIL CLOSED. Overall CI red, not activation/adoption success. Local Python3.12.9 full1880passed/7warnings/177.27s incl315quality cases; frontend/assets/checker Ruff/diff passed. Exact-head isolated all-check exit1 counts84/0/0/196/1. No analysis-error exit2.

Contributor commands unchanged: python -m pip install -r requirements.txt; python -m pip install pytest pytest-asyncio pytest-mock jsonschema; python -m pip install -r requirements-quality.txt; python -m pytest -q --junitxml=.artifacts\pytest.xml --tb=short; python -I -S .github\scripts\check-quality.py --check all --base-ref origin/develop --report .artifacts\quality.json --test-results .artifacts\pytest.xml. Pins remain Ruff0.16.5/mypy2.3.1/ImportLinter2.14/Grimp3.16. Basec6d0ccb01a40071f82f30bd17c9fe566b3d0ad18 reconciled,0 missingdevelopcommits.

T002/T006/T009/T012/T015/T018/T021/T024/T027/T039 plus orchestrator T045 code/evidence delivered. Human exact approvals/bootstrap adoption/admin activation and live Azure compatibility/recovery remain unperformed. UIv2.6.2/ingestionv2.7.3 unchanged peer contract; recoveryorchestratorv4.1.1 does not undo durable writes. Final PR body reconciled with complete commands/results/file groups/limits. Proceed with your already-authorized final docs build/commit/push/body, no new UI/ing review round. No merge/settings/deploy/publish.

Retained limitations: non-MCP forced anonymous/removed-OBO retry/API-key env fallback/legacy token and search-context setter continuation NOT newly approved or strictOBO; nullable providers can still generate ordinary ungrounded answers. HTTP partial config writes and detached Cosmos writes are not rollback/durable-completion assurance; exact2tail reconciliation is not idempotency. Optional memory chat_options/options/value gap is characterization, not accepted extraction/additional retention. Graph/handle_exception/filepath helpers have no maintained callers; no ACL claim. Foundry response bodies and affected diagnostic payloads bounded, not global telemetry privacy certification. Parent's returned37-case legacy slice integrated; own74 new helper/Foundry cases plus exact bindings integrated.