Handoff Proof: a local-Qwen evidence bundle for small Python AI apps

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 2: Side Hustle.

AI writing disclosure: This article draft was written primarily by an AI agent under human direction and should be marked Fully Autonomous in DEV's disclosure control if published in substantially this form. The human submitter must review its claims and remains accountable for publication. That writing assistant is separate from the product's locally running Qwen model, which analyzes Python source at runtime.

What I Built

A small Python tool can look easy to hand over until its new owner asks, “Which file do I run, what data does it need, and how do I know I got the right answer?” I built Handoff Proof for that moment. It is a Windows Python CLI prototype that turns a source folder and a stated goal into a reviewable execution plan, a tested delivery bundle, and evidence of what actually happened.

Current execution boundary: the CLI can analyze a source folder, but verification and bundle creation currently execute only thirteen newly authored, hash-pinned synthetic samples. An arbitrary user project can be analyzed but cannot be run by this prototype.

The potential Side Hustle is a focused handoff review for freelancers, small agencies, and people who build one-off AI apps for clients. They could pay for a reproducible source-and-instructions package rather than an unverified “just run this” README. That is a customer hypothesis, not a claim that I have users, revenue, or proven willingness to pay.

The workflow has three gates:

1. A locally running open-weight model identifies the Python entry file, cites actual source lines, and lists likely external dependencies. The tool inventories and hashes the selected source files.
2. The CLI displays the file list, command, fixed arguments, independently specified expected result, and a plan fingerprint for a person to review. Its verify --approve field requires that exact fingerprint. Model text is never executed as a shell command. The automated evidence runs below passed the fingerprint programmatically; they do not demonstrate a person's approval.
3. The verifier runs only a hash-pinned synthetic sample in a fresh copied directory and Python venv. It checks process output or the generated artifact hash, builds a bundle with source, RUNME.md, dependency information, actual result, and SHA-256 manifest, then copies that finalized bundle and reruns it. A sibling evidence file records the replay.

This goes beyond generating setup prose: a wrong result can fail even when Python exits 0. It is still a prototype. The current verifier deliberately rejects arbitrary user programs because a venv is not an OS security sandbox. The ability to analyze a source folder should not be mistaken for permission to execute it safely.

Demo

Video demo: Watch or download the 51-second MP4 on GitHub (direct verified MP4).

The video is a labeled rendered walkthrough of real local run records, not a live terminal screen recording. It shows the Qwen-cited plan, its review fingerprint field, and two actual finalized-bundle outcomes from the same synthetic CSV. The evidence capture script supplied each fingerprint automatically; the separate CLI supports a person reading the plan and entering --approve:

Reviewed sample	Independent CSV total	Generated HTML total	Python exit	Handoff Proof verdict
Normal calculation	2500 KRW	2500 KRW	0	Passed; expected HTML SHA-256 matched
Deliberate +1 calculation defect	2500 KRW	2501 KRW	0	Failed; expected HTML SHA-256 mismatched

Both cases replayed from copies of their finalized bundles. A separate audit ran those bundles from new folders and venvs without PYTHONPATH or the original project path in the executed command. It matched the report files and file hashes. These were tests on one PC, not proof of security isolation or portability to another machine.

I also tested missing input, invalid configuration, changed row order, and an added row. During review I corrected a misleading early case: its CSV itself summed to 2501 KRW, so it tested a mismatch between the input and the approved 2500 KRW expectation, not a calculation bug. I kept that result labeled separately and created the identical-input +1 code defect above to test the real calculation-error claim.

Code

Public repository: Handoff Proof source, tests, synthetic samples, and demo.

The repository package includes the Python CLI, reviewed synthetic samples, tests, an MIT license for its original code, a README with exact reproduction commands, and path-free validation summaries. Qwen weights and the Ollama runtime are not bundled. The model must already be available locally; the code neither downloads it nor falls back to a cloud AI API.

How I Built It

I started this new project on October 14, 2026. The product's AI work is performed at runtime by qwen2.5:14b served through local Ollama on 127.0.0.1:11434. Qwen reads selected, screened source excerpts and returns a structured entry-file proposal and citations. The Python code checks each citation against the actual included source line and refuses a model-proposed entry that is not an included .py file. In one missing-file test, Qwen initially returned __main__.main; the plan was rejected before any execution. One bounded retry supplied the validation error and allowed file paths, and the accepted plan records two attempts. The initial raw response was not saved, so I do not present a reconstructed transcript.

The verifier does not ask Qwen to declare success. For the report test, the expected HTML was computed separately from the CSV, config, and template, then supplied as the approved SHA-256 assertion. The program's exit code, produced file, exact hash, source hashes, and finalized-bundle replay determine the verdict. Failure logs can be summarized by the local model, but they remain failures. In one invalid-config case, Qwen identified the currency problem while giving an imprecise manual check, so its explanation is advisory rather than proof of a fix.

The staged code ran 37 tests: 36 passed and one Windows symlink-creation test was skipped because this host could not create the link. Measured Qwen analysis for four report cases took 84.76–96.79 seconds each on this CPU-backed setup. A fresh demo-evidence run measured 203.05 seconds for the normal plan and 110.70 seconds for the defect plan; their verification steps took 1.51 and 1.52 seconds. A separate same-PC replay of seven finalized bundles took 0.58–0.63 seconds per case, including venv creation. Those numbers describe this machine and these tiny samples only.

Limits matter here: only thirteen newly authored, pinned samples can execute. No external packages are installed. Secret-pattern checks can miss sensitive material, so every included file requires human review. Fresh folders and venvs do not isolate arbitrary Python from the host or network. There has been no different-PC test, production customer, or payment flow.

Why Does Open Innovation Matter?

The open-weight model is part of the product workflow, not merely a coding assistant used to write the repository. It extracts project-specific run evidence and interprets real failure logs when the verifier finds them. Running Qwen locally let me test that workflow without sending the synthetic source to an external AI service or paying a per-request API charge. It also leaves the prompt, citation checks, and model choice inspectable and changeable by the project owner. Local inference still costs disk space, RAM, CPU time, and electricity; it is not free or automatically fast.

The Qwen2.5-14B-Instruct model card lists Apache-2.0, and Ollama uses MIT. Handoff Proof's MIT license for its original code is separate from those components. Open components made this local-first experiment possible while allowing the handoff evidence and its limitations to be inspected, challenged, and improved.