Repository engineering instructions

Authority

Ken Schaefer owns business decisions, architecture authority, priorities, permissions, spending, and external actions.
ChatGPT provides technical direction and acceptance criteria.
Codex implements approved work orders and reports verifiable results.
Research or drafting never authorizes applications, prospect/employer contact, spending, data sharing, or external commitments.

Prefer Python's standard library and existing dependencies. Favor simple, source-specific modules; avoid frameworks and unnecessary abstractions.
Use PEP 8 conventions, four-space indentation, descriptive names, module docstrings, useful function docstrings, and whitespace between logical steps.
Explain intent, assumptions and non-obvious behavior with comments, including small details where they matter. Do not merely narrate obvious syntax.
Preserve provenance, original-source links, conflicting source evidence and human review decisions. Handle missing/uncertain data explicitly.
Never silently overwrite reviewed pipeline records or historical evidence. The canonical pipeline is data/opportunities.json; historical output is in runs/. Test fixtures belong in tests/fixtures/.
Keep collectors under src/opportunity_intelligence/collectors/, qualification under qualification/, diagnostics under tools/, and procedures under docs/.

Inspect actual source, tests, documentation, paths and Git status before edits.
Make the smallest change that satisfies the approved work order.
Run applicable tests after changes: from the root, python -m unittest discover -s tests -v (Python 3.10+).
Use python w1.py --help for application commands. Offline fixtures are the default for regression verification; network access is not needed for tests.
Report actual results, exceptions and limitations. Code written is not proof that a capability works; execute and verify it before claiming completion.

Obtain direction before new external services, dependencies with recurring costs, credentials, public deployments, data-sharing arrangements, or substantial architectural changes outside the approved work order.
Do not expand scope or begin another increment without approval.
If an assumption proves incorrect, document it and make a small reversible correction within scope, or request direction where scope/authority changes.