[v5.5] Guardrails: clean-base verification + stdlib smoke harness

[lil-aditya]

Closes #389
Part of #388 (v5.5 upstream sync)

Reviewed issues: #375 (Foundational CI/CD Infrastructure): Helps as it adds a lightweight CI check (Python 3.11 smoke/verify). It’s not a full CI/CD framework, but it’s an early building block.
#388 (Absorb selected MUIO v5.5 changes on origin/main): Here #402 directly helps as it(#402) is a prerequisite for the v5.5 absorption work by providing a repeatable “landing gate” so upstream pulls are safer and more predictable.
#402 doesn’t define contribution intake rules/process i.e for #255 ; that goes into #393 separate.

Summary

This PR introduces the guardrails required before pulling upstream MUIO v5.5:

• Maintainer playbook for upstream sync (docs/dev/upstream_sync_playbook.md)
• Clean-base verification script (scripts/verify_clean_base.py)
• Minimal stdlib unittest smoke harness (tests_smoke/)
• Optional CI job running verification on Python 3.11
• CONTRIBUTING.md updated with run instructions

How to run

python scripts/verify_clean_base.py

What this checks

• Active git merge/rebase state (.git/*HEAD)
• Conflict markers in source files
• Python syntax (py_compile)
• Smoke tests (app import + basic routes)

Constraints respected

• No dependency additions
• Uses stdlib unittest only
• Does not assume writable repo root

Known caveats

• Local run may fail if repo is in active rebase state (.git/REBASE_HEAD)
• Local Python 3.13 may not fully support runtime; CI uses Python 3.11

Out of scope

• No backend/runtime merge ([Task] Pull the safe backend/runtime changes from MUIO v5.5 #390)
• No UI changes ([Task] Port the DataFile model/log diagnostics from MUIO v5.5 #391)
• No result metadata updates ([Task] Fix result metadata and shadow-price rendering from MUIO v5.5 #392)

Checklist

• Verification script exits correctly
• Smoke tests run via unittest
• Detects real git merge state
• No writable root assumption
• Maintainer doc added

[Copilot]

Pull request overview

Adds a small “guardrails” layer to make upcoming upstream MUIO v5.5 syncs safer and more repeatable by providing a single clean-base verification command, a minimal stdlib smoke harness, and documentation/CI wiring.

Changes:

• Added scripts/verify_clean_base.py to detect unresolved git operations, conflict markers, py_compile failures, and run stdlib smoke tests.
• Added tests_smoke/ unittest harness to validate API app import and a few fixed routes.
• Added maintainer playbook + CONTRIBUTING update, and a GitHub Actions smoke workflow on Python 3.11.

Reviewed changes

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

Show a summary per file

File	Description
tests_smoke/test_smoke_app.py	Adds stdlib unittest smoke tests for app import and a small set of routes.
scripts/verify_clean_base.py	Implements the clean-base verification script (git state, conflict scan, compile, smoke tests).
docs/dev/upstream_sync_playbook.md	Documents the upstream sync order, overlap surface, rejected patterns, and verification command.
CONTRIBUTING.md	Adds contributor-facing instructions for running clean-base verification.
.github/workflows/smoke.yml	Adds CI job to run the verification script on PRs using Python 3.11.

---

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

[Copilot]

resolve_git_dir() returns a candidate path for worktrees/submodules but never verifies it exists. If .git points at a missing/nonexistent gitdir, check_unresolved_git_state() will silently treat the repo as clean. Consider checking candidate.exists()/candidate.is_dir() and returning None (or an explicit failure message) when the resolved git dir is invalid.

Suggested change

	candidate = (root / candidate).resolve()
	candidate = (root / candidate).resolve()
	# Only return a git dir that actually exists and is a directory.
	if not candidate.exists() or not candidate.is_dir():
	return None

[Copilot]

iter_repo_files() checks SKIP_DIR_NAMES against path.parts, but path is absolute, so any ancestor directory named e.g. venv/node_modules will cause all repo files to be skipped (false negatives for conflict/compile scanning). Use path.relative_to(root).parts (or equivalent) for the skip check so only paths within the repo influence filtering.

[parthdagia05]

396 opened by @sanvishukla pls check out

[brightyorcerf]

I've taken a look at the guardrails here, and while the structure aligns with the #389 requirements, there are a few architectural risks that might impact the Stability Track for v5.5:

• The 'No Writable Root' Constraint: The current smoke harness and py_compile logic will still attempt to write pycache directories to the source tree. In a strictly read-only environment (like a locked GSoC CI runner), this will cause an OSError. We should probably set sys.dont_write_bytecode = True to ensure 100% compliance with the 'no-write' rule.

• Absolute Path Logic Risk: The current iter_repo_files filters path.parts on absolute paths. If a developer happens to store the project in a path containing a skip-name (like /Users/name/venv/MUIOGO), the script will skip every file in the repo. Switching to path.relative_to(root).parts would make this more robust.

• Pathlib Consistency: To stay aligned with the new institutionalized standards we've just landed in the logic layer, we should swap the remaining os.remove and os.close calls for native Pathlib .unlink() operations to maintain an OS-agnostic architecture.

Happy to help refine these so we have a bulletproof landing gate for the v5.5 upstream pull.

[lil-aditya]

Hello @brightyorcerf thanks for the suggestions and I’ve gone through them:

1. pycache / writable root

Good catch. Since the goal of the guardrail is to work even in read-only environments, it makes sense to avoid any bytecode writes.
I’ve wrapped the script execution with sys.dont_write_bytecode = True (and restore it after), so it won’t try to create __pycache__ during verification or smoke runs.

---

2. Path filtering in iter_repo_files()

Agreed — using absolute path.parts could cause incorrect filtering if something like a parent folder name matches (e.g., venv).
I’ve switched this to use path.relative_to(root).parts so filtering is based only on paths inside the repo.

---

3. Pathlib consistency (os.remove / os.close)

I took a look at this, but I don’t think it’s necessary for this PR.
The script is already mostly using Pathlib where it matters, and these calls aren’t causing any portability issues right now.
So I’ve left this out to keep the PR focused. We can always clean this up later in a separate pass if needed.

[brightyorcerf]

Appreciate the quick turnaround on the bytecode suppression and the path-filtering fix, @lil-aditya. Those were the primary risks for the v5.5 Stability Track.

[SeaCelo]

@lil-aditya Thanks for the work here. We have now landed the v5.5 guardrail/smoke work through #422 in a different form via the upstream sync notes, landed smoke scripts, and landed smoke tests, so I’m closing this v5.5-specific PR. The remaining CI workflow piece belongs under the broader CI track with #375 / #204 rather than keeping this open as sync work.