Guided Setup Evidence Doctor 20260801

Overview

This net-new draft implements the 2026-08-01 Merlin priority for Setup/UX Recovery Doctor. Its stdlib-first analyzer converts redacted local evidence notes into a deterministic evidence-gap report. It checks for: platform version, runtime version, install method, dependency check, port check, service state, redacted error, reproduction step, expected state, observed state, restore point, repair owner, verification step.

The analyzer is advisory and read-only. It does not execute repairs, install third-party code, discover private data, call networks, control services, alter configuration, schedule work, publish, package, deploy, or initiate financial activity. A local result is not an independent downstream release or security verdict.

When to Use

• When turning redacted setup observations into a guided evidence-gap diagnosis without changing the machine.
• When a reproducible PASS, REVIEW, BLOCKED, or ERROR report is needed.
• To prepare deterministic clean, risky, missing, guarded-path, and oversized-input cases for independent Viper QA.

Do not use this skill as authorization to mutate a system or as proof that an artifact is safe for release.

Safety Contract

• Reads only direct --text or one explicitly supplied local notes file.
• Refuses hidden or sensitive-looking paths, symlinks, non-files, and inputs over 200,000 characters.
• Uses Python standard-library modules only and always reports mutated_files: [].
• Does not inspect environment variables, identity material, private records, or remote resources.

Main Script

scripts/guided_setup_evidence_doctor.py supports --notes, --text, --self-test, and --json.

Operator Workflow

1. Prepare redacted evidence notes. Complete when no secrets or private personal information are present.

2. Run python3 scripts/guided_setup_evidence_doctor.py --notes notes.txt --json. Complete when structured output is returned and source content is unchanged.

3. Review every risk and missing signal. Complete when each finding has an owner or explicit deferral.

4. Hand unchanged artifacts and local evidence to Viper. Complete while the draft remains PENDING_VIPER.

Result Semantics

• PASS: at least nine expected signals and no risk signal.
• REVIEW: partial evidence or one bounded concern.
• BLOCKED: at least two risks or an evidence score below 25.
• ERROR: missing, guarded, oversized, or unreadable input.

Test Scenarios

• Complete signal evidence should produce PASS.
• Two or more explicit risk phrases should produce BLOCKED.
• Missing input should return ERROR with missing_notes.
• Hidden, sensitive-looking, symlinked, directory, and oversized inputs should be refused without mutation.

Common Pitfalls

1. Treating a local analyzer result as independent approval.

2. Supplying secret values instead of redacted evidence references.

3. Mistaking recommendations for authorized repair or execution.

4. Omitting ownership, restore, rollback, timestamp, or reviewer evidence.

Verification Checklist

• [ ] python3 -m py_compile scripts/guided_setup_evidence_doctor.py exits 0 with bytecode redirected outside the source directory.
• [ ] Two --self-test --json runs are byte-for-byte identical.
• [ ] Self-test returns ok=true, clean=PASS, risky=BLOCKED, and mutated_files=[].
• [ ] Input guards and repository security/static checks pass.
• [ ] Draft remains PENDING_VIPER for independent review.

Draft Status

PENDING_VIPER — Iceman build evidence is not an independent downstream verdict.