Development and CI

Development and CI

OSINT Forge treats tests, documentation, permissions, packaging, migration safety, and clean installation as release requirements.

Local checks

./scripts/dev-check.sh

The v0.5.0 release gate compiles Python, runs 97 deterministic tests, validates all eight plugin contracts, checks shell syntax and executable modes, and runs ShellCheck when installed. It also works from extracted archives without Git metadata.

Exact-commit QA harness

./scripts/qa-harness.py --help
./scripts/codex-qa.sh release
./scripts/codex-qa.sh status
./scripts/codex-qa.sh attach

The harness binds evidence to an exact commit, records atomic checkpoints and per-step exit codes, verifies hosted checks and archives, enforces owner-only evidence permissions, and creates tamper-evident manifests. The launcher runs Codex in a persistent tmux session on the dedicated Debian VM; detaching does not stop QA. Release mode is authorized for testing and corrective patch loops but not tagging or publication.

GitHub Actions matrix

Every pull request runs seven required jobs:

• Python 3.10, 3.11, 3.12, and 3.13 with plugin contracts;
• shell quality and ShellCheck;
• clean install, upgrade, integration, lifecycle, and uninstall on Debian stable; and
• the same clean-system coverage on Ubuntu 24.04. Actions are pinned to immutable commit SHAs and maintained through Dependabot.

Architectural test expectations

Changes receive focused coverage for affected behavior. As the v1.0 intelligence workflow develops, tests must cover:

• schema validation, migration, and unknown-version rejection;
• target and entity normalization without provenance loss;
• deterministic deduplication and stable identifiers;
• source assertions, inferred relationships, analyst findings, and confidence as separate concepts;
• adapter accepted/emitted entity contracts;
• planner previews, resume, concurrency, and failure isolation;
• evidence hashes, manifests, and export verification;
• correlation explanations and confidence inputs;
• recursion scope, depth, budgets, loop prevention, approval, and audit history;
• path, symlink, permission, and reserved-artifact safeguards; and
• backward compatibility for existing CLI, plugin, batch, and case workflows. Use only synthetic data. Never place real targets, credentials, tokens, case files, or investigation output in tests or logs.

Pull requests and documentation

Create a focused branch, commit only intended files, explain user impact, list validation, and open a draft pull request. Required checks must pass before merge. Update canonical repository documentation in the same change when contracts or behavior change. The wiki is updated separately when the published operational guidance is ready. Review the Contributing Guide, versioned roadmap, AI Development Policy, and Governance and Maintainer Authority.

Release gate

Merge and hosted CI success do not authorize a release. Release Process is sequential: after merge and before tag/publish, the exact candidate receives comprehensive testing on a current Debian VM. Testing may be human-operated with AI assistance or autonomously executed by an AI under explicit owner authorization and complete evidence-retention requirements. Any discovered defect is patched, merged, and retested before release. After publication, the release remains open until its Discussions announcement, changelog link, applicable repository documentation, applicable wiki pages, and final administrative verification are complete.