datapulse-my: Instructions file for Codex

AGENTS.md — r3dz4r/datapulse-my

Working agreement for AI agents (Hermes, Codex, Claude Code) operating inside this repository. Read once, then follow on every change.

What this repo is

r3dz4r/datapulse-my — open-source trust layer for Malaysian public data. 440 official datasets from data.gov.my, BNM, DOSM, DOE, KKM, KPDN, MET Malaysia continuously probed and classified into a 10-status taxonomy (fresh | aging | stale | discontinued | degraded | browser_dependent | unreachable | unknown | unknown_freshness | reference). Live MCP server with 19 read-only tools (canonical count: jq '.tools | length' mcp.json — do NOT hardcode this number in prose). Hosted on https://www.data-pulse.my and https://mcp.data-pulse.my.

One-line constraint: every change here is publicly visible. The dashboard auto-deploys on push to main (modulo [skip deploy] trailers). Bad data leaks fast.

Hard rules

1. Do not write/edit/refactor code. Dispatch codex-run (with a tight brief). You may edit .gitignore, commit messages, and markdown files under docs/ — those are operator-owned. A dispatched worker is the exception and must write the scoped code itself: this rule addresses the Hermes orchestrator, not the worker, and it does not authorise a worker to dispatch another agent. A worker that stops because it read this rule as applying to itself has misread it — report any other conflict, but not this one.
2. No --yolo, no bypassing preflight gates. The deterministic-safety-net job in .github/workflows/ci.yml must stay green. If it fails, fix the gate (or the brief that fed into it) — don't silence the failure.
3. Push requires explicit "push". "Proceed" / "go" / "dispatch codex" authorises only the immediately preceding, clearly scoped action. "Push" must be literal.
   • Exception — the health-automation publish lane merges itself (operator decision 2026-10-23). .github/workflows/health-automation-merge.yml merges health-automation into main on green, using the datapulse-release App, with autoMerge=true. Measured on PR #2629: merged 2026-10-23T13:29:37Z by app/datapulse-release before any operator word was given. The gate on that path is the required checks — deterministic-safety-net and the isolated preview — not a human message, so no agent should ask for "push" to release a health-automation publish; asking after the fact is how a completed merge gets reported as pending. The literal word still governs every other push: operator commits, source changes, release-please, attestation appends, and anything merged by hand.
4. Never silently rotate credentials, edit firewall rules, or stop systemd services on the public-facing VPS (https://data-pulse.my). These are always-ask.
5. No upstream mutations. Datapulse MY is read-only by design. New code must NOT write to data.gov.my, BNM, DOSM, or any other upstream. If a use case requires writes, that's a different product — not this repo.
6. The 10-status taxonomy is stable. Adding a status requires changing gen_health_methodology.py, embed_dashboard_data.py, gen_changelog.py, the dashboard hero, mcp/server.py, AND the public-facing methodology page. If you think you need an 11th status, surface it to the operator first.
7. All 4 MCP tool annotations are mandatory on every tool — see mcp/AGENTS.md for the canonical list. OpenAI's directory and M8ven both reject tools missing hints.
8. Tests live next to code. mcp/tests/ for the server, scripts/tests/ for the generators. New code needs new tests; coverage floor is enforced by the deterministic-safety-net gate.
9. Every committed artifact is a generator output — nothing here is maintained by hand. A change to any artifact is a change to the generator that emits it, or to the canonical source that generator reads, followed by regeneration; a hand-edit is not a path, and hand-edits get overwritten on the next timer tick. Artifacts (generated, never hand-edited): datapulse.json, health/, record-evidence/, .attestations/, data/, docs/index.html, changelog.json, mcp.json, catalog-snapshot.json. Sources (authored, then consumed by generators or validators): the scripts/ themselves, config/, templates/, and the two schema files. A source is not an artifact: it is read, never regenerated in place. Two gaps against this rule are open and recorded rather than hidden — datapulse.schema.json and health.schema.json have no generator, and the manifest's dataset rows come from no generator either. Do not describe either as hand-authored; describe them as gaps.
10. Deploy posture is read-only + fail-closed. If a probe fails, mark the dataset stale or unreachable — do not silently retry until it works.