# AGENTS.md — Operational Instructions for AI Agents & Contributors

This document defines the mandatory operating protocols, progressive context loading hierarchy, and safety constraints for AI agents working in the **Zyphon** repository.

---

## 1. Core Operating Philosophy: Context Optimization

> **DO NOT LOAD THE ENTIRE REPOSITORY OR ENTIRE DOCUMENTATION TREE BY DEFAULT.**  
> Optimize for **accurate, minimal context retrieval**. Retrieve only what is directly required for the current task.

---

## 2. Mandatory 5-Level Progressive Context Loading Workflow

Every task executed by an AI agent must strictly follow this progressive funnel:

```
[Level 1] High-Level Orientation
   ├── Read AGENTS.md (this file)
   ├── Read PROJECT.md (project map)
   └── Read .project/manifest.json & .project/status.json
           │
           ▼
[Level 2] Module Identification
   ├── Identify the target module (e.g., apps/gateway, packages/config, providers/email)
   └── Read the module definition in .project/graph/modules.json
           │
           ▼
[Level 3] Dependency & Entity Discovery
   ├── Query .project/graph/apis.json for relevant endpoints
   ├── Query .project/graph/dependencies.json for internal/external links
   ├── Query .project/features.json and .project/decisions.json for related ADRs
   └── Frame task context using .project/context/current-task.schema.json
           │
           ▼
[Level 4] Targeted Source & Deep Documentation Reading
   ├── Read ONLY the specific source files identified in Level 3
   └── Read ONLY the specific deep documentation sections required (e.g. docs/DESIGN.md#section)
           │
           ▼
[Level 5] Execution, Testing & Continuous Synchronization
   ├── Plan and implement code changes
   ├── Run relevant test suites
   ├── Perform change impact analysis
   ├── Synchronize .project/ graph and documentation
   └── Run validation via scripts/validate-intelligence.js
```

---

## 3. Fact Classification Rules

When reading or updating project intelligence, classify every knowledge item into one of the following five states:

| Classification | Definition | Rule |
| :--- | :--- | :--- |
| **FACT** | Confirmed by code implementation, runtime configuration, test suite, or explicit requirement. | May be recorded as an established fact. |
| **ASSUMPTION** | Reasonable inference that has not yet been directly verified. | Must be explicitly labeled as an assumption. Never convert assumption → fact without verification. |
| **PROPOSAL** | Recommended future approach or design suggestion. | Never label a proposal as a fact. |
| **PLANNED** | Explicitly intended functionality documented in roadmaps or task backlogs. | Never claim planned work as implemented. |
| **UNKNOWN** | Cannot currently be determined from available repository evidence. | State unknown honestly; do not invent answers. |

---

## 4. Non-Negotiable Architectural & Security Guardrails

1. **Zero-Database Mandate (RULE 1.1)**:
   - Under no circumstances may any external database driver (`pg`, `mysql2`, `mongodb`, `redis`, `better-sqlite3`, Prisma, TypeORM, Drizzle) be added as a dependency.
   - All state is derived from `config/*.yaml` manifests, process environment variables, and in-memory rolling ring-buffers.
2. **Zero Plaintext Secrets (RULE 2.1)**:
   - Never commit API keys, tokens, or credentials into source files or configuration manifests.
   - Always reference secrets using `${ENV_VAR_NAME}` placeholders.
3. **Fail-Closed Channel Access Control (RULE 4.1)**:
   - If an application does not have an explicit entry in `allowedChannels` within `config/applications.yaml`, all dispatch attempts to that channel must fail immediately with HTTP `403 Forbidden`.
   - Never implement wildcard channel permissions (`*`).
4. **Normalized Error Taxonomy (RULE 6.1)**:
   - Upstream client callers must receive standardized error objects (`PROVIDER_TIMEOUT`, `INVALID_RECIPIENT`, etc.).
   - Never leak internal provider stack traces, authorization tokens, or sensitive response headers to API callers.
5. **Production Safety (RULE 32)**:
   - Never run commands against production environments, restart production pods, or modify live production configurations without explicit human authorization.

---

## 5. Development Lifecycle & Continuous Synchronization

Before completing any development task, answer these questions:
- *Did architecture or data flow change?* → Update [`.project/graph/architecture.json`](.project/graph/architecture.json) and [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md).
- *Did an API endpoint or request payload change?* → Update [`.project/graph/apis.json`](.project/graph/apis.json) and [`docs/DESIGN.md`](docs/DESIGN.md).
- *Did configuration schemas or parameters change?* → Update [`config/*.yaml`](config/) and [`.project/graph/modules.json`](.project/graph/modules.json).
- *Did a feature status transition (planned → implemented)?* → Update [`.project/features.json`](.project/features.json) and [`.project/status.json`](.project/status.json).
- *Was an architectural decision made?* → Update [`.project/decisions.json`](.project/decisions.json) and [`docs/MEMORY.md`](docs/MEMORY.md).
- *Did you run drift validation?* → Execute `node scripts/validate-intelligence.js`.

---

## 6. Prohibited Actions
- ❌ Do NOT read the entire repository tree repeatedly when a task affects an isolated module.
- ❌ Do NOT rewrite working code or replace Fastify/YAML without explicit user instruction.
- ❌ Do NOT invent unverified APIs, dependencies, or implementation statuses.
- ❌ Do NOT create redundant documentation files when the `.project/` graph can index existing files.

<!-- BEGIN:turborepo-agent-rules -->

# This is NOT the Turborepo you know

Turborepo configuration, task behavior, and CLI commands can vary between installed versions and may differ from your training data. Resolve the `turbo` package from this file's directory or relevant workspace; in monorepos, it may not be visible from the repository root. For example, run `node -p "require.resolve('turbo/package.json')"` from a workspace that depends on `turbo`.

Read `docs/README.md` inside that installed package first, then read the relevant pages from its `docs/` directory before changing Turborepo configuration or commands. Heed deprecation notices. These bundled docs match the installed package version and are available without network access.

This block is written and re-added by `turbo` before repository-scoped commands when an AI agent is detected. In the Turborepo source repository, its template is defined in `crates/turborepo-cli/src/cli/agent_guidance.rs`. Removing the managed block while updates are enabled means a later qualifying invocation will add it again. Set `"agentGuidance": false` in the root `turbo.json` or `turbo.jsonc` to opt out; this does not remove an existing block. Keep the block committed with your work to avoid an uncommitted change on the next agent invocation.
<!-- END:turborepo-agent-rules -->