Skip to content

AGENTS.md

Latest commit

 

History

History
99 lines (67 loc) · 5.31 KB

AGENTS.md

File metadata and controls

99 lines (67 loc) · 5.31 KB
Raw

Agent Instructions

Platform governance

Read .github/instructions/governance/ for compiled ADRs, invariants, and open questions. These are the platform rules. Do not assume rules not in the governance reference.

Platform repos (read these for full context when accessible):

If no spec exists for what you're asked to build — STOP implementation. Draft or request the missing spec first. Do not invent product behavior in code.

Authority tiers for required-gate failures

A required CI gate failure may be classified as out-of-scope only when a ratified ADR-### or OQ-### in the architecture governance registry explicitly names that failure and grants the deferral. Two requirements must both be met:

  1. The cited number must exist in the governance registry and be ratified by the owner.
  2. The cited number's actual subject in the registry must match the failure being deferred. Citing a real OQ number whose registry content concerns a different topic is not authority — it is a false citation, which is worse than citing nothing.

Working documents in this repo (TRACKER.md, GATE-AUDIT-PAM003.md, sprint docs, this file) are not deferral authority. An entry there is a request for a deferral, never the deferral itself. Agents can write into those documents; the owner ratifies in the governance registry.

If you cannot cite a ratified ADR or OQ whose subject matches the failure: report the failure verbatim, state the gate is "failing and unratified," stop, and ask the owner for a ruling. Do not label a failing gate "no action needed," "pre-existing," or "pending OQ-###" unless the OQ number is real, ratified, and on-subject.

Repo-specific rules

SPARXSTAR Sirus Context — Agent Instructions

Who reads this file

AI agents operating in this repository. Read this alongside .github/copilot-instructions.md.

Platform position

Ouroboros → Helios → Sirus → Sky → Mehns → Dheghom

Sirus is the platform kernel. It loads first as a mu-plugin. Everything else depends on the context it produces. It receives nothing from downstream layers.

The following files provide the full tech specs for the project:

The UEC migration

sparxstar-user-environment-check is in production on a live site. Sirus replaces it transparently via the StarUserEnv shim.

Migration strategy: Transparent Proxy.

  • Sirus boots and populates its environment record on every request.
  • StarUserEnv proxies all calls to Sirus internals.
  • No calling code changes.
  • For the first 30 days post-deployment, fail-closed rules apply only to new /sparxstar/ and /aiwa/ endpoints.
  • After stabilisation, fail-closed rules extend to all governed paths.

Do not break StarUserEnv. Its signatures are a permanent contract.

Why the client is the source of truth for environment

Server-side User-Agent parsing is unreliable. Matomo DeviceDetector is used for UA parsing but the client-side signals (visitorId, canvas hash, screen resolution, timezone) are the primary fingerprint inputs. visitorId is client-side derived, probabilistic, used for drift detection only. It is NOT a security primitive. The server-issued device_id is the real persistent identity.

Why Sirus is a mu-plugin

Sirus must establish context before any standard plugin, theme, or authentication hook can execute. A regular plugin can be deactivated. A mu-plugin cannot. The boot order is enforced by the loader: mu-plugins/00-sparxstar-loader.php requires Sirus first.

Why ContextBootException must never be swallowed

If ContextEngine::current() throws and the exception is caught and ignored, every downstream decision operates on undefined state: Helios agreement uses an undefined device_id, Triple Binding in Dheghom uses an undefined session, governance evaluation uses an undefined authority. There is no recovery from missing context. There is only halt.

Cross-repo dependency check

Before implementing any validation logic, search Ouroboros for ValidationHelper. Before implementing any exception, check Ouroboros exceptions. ContextBootException is defined in Ouroboros --- do not re