Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
39 lines (28 loc) · 2.4 KB

CONTRIBUTING.md

File metadata and controls

39 lines (28 loc) · 2.4 KB
Raw

Contributing

Contributions are welcome when they keep the repository useful without weakening its public/private boundary.

Development checks

Run from the repository root:

python ./tests/smoke.py
python ./tests/artifactctl_test.py
pwsh -NoProfile -File ./tests/smoke.ps1
pwsh -NoProfile -File ./tests/interop.ps1
pwsh -NoProfile -File ./tests/prepublish-smoke.ps1
pwsh -NoProfile -File ./scripts/prepublish-check.ps1

Python is the preferred cross-platform lifecycle runtime. Windows PowerShell 5.1 remains supported, and changes to the memory protocol must pass the Python/PowerShell interoperability test.

Privacy rules

  • Use fictional placeholders in tests and documentation.
  • Do not commit a real vault, local configuration, credentials, user profile, soul, project history, or handoff.
  • Do not weaken ignore rules or make the tool follow the .agent-vault link during publication checks.
  • Keep .codex/hooks.json as the only tracked project source under .codex. Never publish Codex logs, caches, approvals, or generated state.
  • When changing scripts/agent-startup-context.py, update all four pinned SHA-256 occurrences in .codex/hooks.json. The publication check rejects stale pins, and users must review the changed hook definition again.
  • When changing scripts/artifactctl.py, update both pinned SHA-256 occurrences in the SessionStart hook and refresh the device-local sweeper schedule. Never commit output/; it is a seven-day temporary delivery outbox.
  • New automatic promotion behavior must remain opt-in and reviewable. SOUL.md, approved lessons, and durable preferences are human-governed.

Script lifecycle

  • Keep one-off helpers outside the repository. scripts/ is for durable operator or lifecycle tooling, not task residue.
  • Begin every new or materially rewritten durable script with a concise Purpose, Retention, and Remove when comment or docstring so later maintainers can judge whether it still belongs.
  • Delete task-created temporary scripts, caches, and auxiliary files when their work is complete. Do not delete pre-existing or ambiguously owned scripts without explicit approval.
  • A script promoted into scripts/ should have the smallest useful test or documentation reference demonstrating its durable role.

Pull requests

Explain the behavior change, the threat or failure mode it addresses, and the checks you ran. Keep platform-specific behavior explicit.