Spaghetti

Spaghetti is a no-admin desktop package for SDMs. It builds PM_SDM_Pilot.zip, which installs a per-user desktop launcher named Spaghetti. The launcher signs in through Snowflake browser SSO, builds the SDM-specific HTML report, and writes a dated Desktop report named Spaghetti_yyyy-mm-dd.html.

Owner workflow

1. Create and push a v* release tag.
2. Let the Spaghetti Release Package workflow build, audit, checksum, publish, and download-back verify PM_SDM_Pilot.zip in a private GitHub Release.
3. Run the work-PC proof before telling SDMs to install the release asset.
4. SDM extracts the zip.
5. SDM double-clicks INSTALL_PM.cmd.
6. SDM clicks Spaghetti.
7. Browser SSO may open.
8. Fresh report appears as Spaghetti_yyyy-mm-dd.html on the Desktop.

Owner-safe doc map

• Setup and local validation: this README.md
• Agent guardrails and required release validation: AGENTS.md
• No-admin safety rules: docs/no-admin-constraints.md
• Package contract and allowed package-root entries: docs/package-contract.md
• Package hygiene checklist and denied categories: docs/package-hygiene.md
• Package release runbook: docs/release-process.md
• Failed install runbook: docs/failed-install-runbook.md
• Failed Snowflake auth runbook: docs/failed-snowflake-auth-runbook.md
• Rollback and re-release runbook: docs/rollback-rerelease-runbook.md
• Non-applicable readiness rationale: docs/readiness-scope.md

No-admin safety rules for every setup and runbook step

• No admin prompt.
• No Program Files writes.
• No HKLM writes.
• No machine PATH changes.
• No manual Python install.
• No SnowSQL dependency.
• No unsigned custom executable.
• No Defender/security workaround.
• No real Desktop mutation during sandbox evidence runs.

Build package

cd C:\repos\Spaghetti
.\scripts\work_pc\BUILD_PM_SDM_PILOT_PACKAGE.cmd

The build writes dist\PM_SDM_Pilot.zip and audits package hygiene.

Local validation

Fresh checkout setup (one-time):

python -m pip install -r requirements-build.txt -r requirements-dev.txt -r requirements-runtime.txt

Copy/paste the canonical local validation entry point from C:\repos\Spaghetti:

python scripts/quality_gates/run_local_validation.py

That one command runs every blocking tooling gate in the inventory below plus the baseline package validators, without admin rights, machine PATH changes, live Snowflake access, or real Desktop mutation.

After any production refactor, also run a strict touched-file complexity check on the changed production Python files:

python -m ruff check --select C901 <changed-production-python-files>

For focused parity and owner-readable failure-path rechecks after wrapper, export, or package refactors, rerun the targeted pytest surfaces in tests/test_wrapper_cli_compatibility.py, tests/test_pm_snowflake_export_characterization.py, tests/test_package_sandbox_proof.py, and tests/integration/test_package_sandbox_integration.py with python -m pytest <target> -q --no-cov -n 0.

If the format check fails, repair it with:

python -m ruff format src scripts tests

Tooling gate inventory

CI mapping values below are the stable GitHub check names emitted by .github/workflows/validation.yml. The one-time fresh-checkout dependency install stays separate from repeat validation because it provisions the environment.

Gate	Assertion(s)	Command	Blocking	Included in run_local_validation.py	CI mapping	Omission rationale
Ruff lint	VAL-TOOL-003	python -m ruff check src scripts tests	Yes	Yes	Spaghetti Validation / Repo quality gates	—
Ruff format check	VAL-TOOL-004	python -m ruff format --check src scripts tests	Yes	Yes	Spaghetti Validation / Repo quality gates	—
Pytest suite (explicit discovery, durations, coverage, env-template checks)	VAL-TOOL-005, VAL-TOOL-006, VAL-TOOL-007, VAL-TOOL-013	python -m pytest tests -q	Yes	Yes	Spaghetti Validation / Pytest suite	—
MyPy type check	VAL-TOOL-008	python -m mypy src scripts tests	Yes	Yes	Spaghetti Validation / Repo quality gates	—
Pre-commit all-files	VAL-TOOL-009	python -m pre_commit run --all-files	Yes	Yes	Spaghetti Validation / Repo quality gates	—
Dependency hygiene	VAL-TOOL-010	python scripts/quality_gates/check_dependency_hygiene.py	Yes	Yes	Spaghetti Validation / Repo quality gates	—
Architecture boundaries	VAL-TOOL-011	python scripts/quality_gates/check_architecture_boundaries.py	Yes	Yes	Spaghetti Validation / Repo quality gates	—
Complexity	VAL-TOOL-011	python -m ruff check --select C901 src/inca_sorter tests scripts	Yes	Yes	Spaghetti Validation / Repo quality gates	—
Tech-debt markers	VAL-TOOL-011	python scripts/quality_gates/check_repo_hygiene.py --check tech-debt src scripts tests pyproject.toml .pre-commit-config.yaml	Yes	Yes	Spaghetti Validation / Repo quality gates	—
Dead-code scan	VAL-TOOL-011	python -m vulture --config pyproject.toml	Yes	Yes	Spaghetti Validation / Repo quality gates	—
Duplicate-code scan	VAL-TOOL-011	python scripts/quality_gates/check_duplicate_code.py --min-lines 40 src/inca_sorter tests scripts	Yes	Yes	Spaghetti Validation / Repo quality gates	Repo-local detector covers tracked Python, PowerShell, and CMD code without adding a Node or Java toolchain.
Large-file guard	VAL-TOOL-012	python scripts/quality_gates/check_repo_hygiene.py --check large-files	Yes	Yes	Spaghetti Validation / Repo quality gates	—
Secret guard	VAL-TOOL-012	python scripts/quality_gates/check_repo_hygiene.py --check secrets	Yes	Yes	Spaghetti Validation / Repo quality gates	—
PII guard	VAL-TOOL-017	python scripts/quality_gates/check_repo_hygiene.py --check pii	Yes	Yes	Spaghetti Validation / Repo quality gates	—
Developer dependency setup	VAL-TOOL-016	python -m pip install -r requirements-build.txt -r requirements-dev.txt -r requirements-runtime.txt	No	No	Repeated Install validation dependencies step in all Spaghetti Validation jobs (non-blocking local setup)	One-time fresh-checkout setup step; intentionally omitted from repeat validation runs so the entry point stays non-mutating after the environment is provisioned.

Baseline validators included by the entry point

python -m pytest tests -q is both a tooling gate and a baseline validator. The local entry point also runs these baseline package validators:

Baseline validator	Command	Included in run_local_validation.py	CI mapping
Compile Python scripts	python -m compileall -q scripts	Yes	Spaghetti Validation / Package and script validation
Parse PowerShell scripts	powershell -NoProfile -ExecutionPolicy Bypass -Command "$files = Get-ChildItem scripts -Filter *.ps1 -Recurse; foreach ($f in $files) { $tokens=$null; $errors=$null; [System.Management.Automation.Language.Parser]::ParseFile($f.FullName,[ref]$tokens,[ref]$errors) > $null; if ($errors.Count) { throw $f.FullName } }; 'parser ok'"	Yes	Spaghetti Validation / Package and script validation
Build and audit PM_SDM_Pilot.zip	powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\work_pc\build_pm_sdm_pilot_package.ps1	Yes	Spaghetti Validation / Package and script validation
Git whitespace check	git diff --check	Yes	Spaghetti Validation / Package and script validation

Live Snowflake/browser SSO work-PC proof remains outside this tooling inventory and is intentionally not mirrored in CI because it is product validation rather than a blocking local tooling gate.

Environment configuration

Environment variables referenced by repository scripts, workflows, and documentation are documented in .env.example with placeholders only. Real values stay in a maintainer's local .env, local Snowflake configuration, or GitHub secrets; never commit secrets, fake credentials, or machine-specific private paths.

Copy it when needed:

Copy-Item .env.example .env

Examples:

• PM_TIMING_EVENTS_PATH (optional): Override timing-events output path.
• PM_QUERY_CORRELATION_PATH (optional): Override redacted query-correlation evidence output path used by local tooling.
• PM_SNOWSQL_CONFIG_PATH (optional): Override Snowflake connector config file path used by local tooling.
• WIKI_AUDIT_PATH (optional): Override wiki-audit project path.
• QA_OPTIONAL_NOTE (optional): PR comment note used by the optional QA workflow.

Work-PC proof

Run this short sequence from C:\repos\Spaghetti on the work PC:

cd C:\repos\Spaghetti; git pull --ff-only; .\scripts\work_pc\CREATE_PM_DESKTOP_ICONS_FROM_PACKAGE.cmd

Then click Spaghetti. Success means a fresh Desktop file named Spaghetti_yyyy-mm-dd.html appears for today's date. If the shortcut is missing, the browser SSO flow fails, or the dated report does not appear, stop and use the linked runbooks instead of debugging internals.

Non-negotiable package constraints

• No admin prompt.
• No manual Python install.
• No SnowSQL dependency.
• No unsigned custom executable.
• No Program Files, HKLM, or machine PATH changes.
• No real Desktop mutation during evidence sandbox runs.
• No repo junk inside PM_SDM_Pilot.zip.

Factory readiness

Factory should start with:

/readiness-report
/wiki
/install-qa

Use docs/qa-critical-flows.md, docs/no-admin-constraints.md, docs/release-process.md, docs/failed-install-runbook.md, docs/failed-snowflake-auth-runbook.md, docs/rollback-rerelease-runbook.md, docs/package-hygiene.md, docs/readiness-scope.md, and AGENTS.md as project context.