# 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.

## Engineering

- 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/`.

## Execution

- 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.

## Change control

- 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.