Redflag/docs/4_LOG/_originals_archive.backup/DEVELOPMENT_ETHOS.md

Development Ethos

Philosophy: We are building honest, autonomous software for a community that values digital sovereignty. This isn't enterprise-fluff; it's a "less is more" set of non-negotiable principles forged from experience. We ship bugs, but we are honest about them, and we log the failures.

The Core Ethos (Principles & Contracts)

These are the rules we've learned not to compromise on. They are the contract.

1. Errors are History, Not /dev/null

Principle: NEVER silence errors.

Rationale: A "laid back" admin is one who can sleep at night, knowing any failure will be in the logs. We don't use 2>/dev/null. We fix the root cause, not the symptom.

Implementation & Contract:

• All errors, from a script exit 1 to an API 500, MUST be captured and logged with context (what failed, why, what was attempted).
• All logs MUST follow the [TAG] [system] [component] format (e.g., [ERROR] [agent] [installer] Download failed...).
• The final destination for all auditable events (errors and state changes) is the history table, as defined in CODE_RULES.md.

2. Security is Non-Negotiable

Principle: NEVER add unauthenticated endpoints.

Rationale: "Temporary" is permanent. Every single route MUST be protected by the established, multi-subsystem security architecture.

Implementation & Contract (The Stack):

• User Auth (WebUI): All admin dashboard routes MUST be protected by WebAuthMiddleware().
• Agent Registration: An agent can only be created using a valid registration_token via the /api/v1/agents/register endpoint. This token's validity (seats, expiration) MUST be checked against the registration_tokens table.
• Agent Check-in (Pull-Only): All agent-to-server communication (e.g., GET /agents/:id/commands) MUST be protected by AuthMiddleware(). This validates the agent's short-lived (24h) JWT access token.
• Agent Token Renewal: An agent MUST only renew its access token by presenting its long-lived (90-day sliding window) refresh_token to the /api/v1/agents/renew endpoint.
• Hardware Verification: All authenticated agent routes MUST also be protected by the MachineBindingMiddleware. This middleware MUST validate the X-Machine-ID header against the agents.machine_id column to prevent config-copying and impersonation.
• Update/Command Security: Sensitive commands (e.g., updates, reboots) MUST be protected by a signed Ed25519 Nonce to prevent replay attacks. The agent must validate the nonce's signature and its timestamp (<5 min) before execution.
• Binary Security: The agent must verify the Ed25519 signature of any downloaded binary against the cached server public key (the TOFU model) before applying a self-update. This signature check MUST include the [tunturi_ed25519] watermark.

3. Assume Failure; Build for Resilience

Principle: NEVER assume an operation will succeed.

Rationale: Networks fail. Servers restart. Agents crash. The system must recover without manual intervention.

Implementation & Contract:

• Agent-Side (Network): Agent check-ins MUST use retry logic with exponential backoff to survive server 502s and other transient network failures. This is a critical bug-fix outlined in your Agent_retry_resilience_architecture.md.
• Agent-Side (Scanners): Long-running or fragile scanners (like Windows Update or DNF) MUST be wrapped in a Circuit Breaker to prevent a single failing subsystem from blocking all others.
• Data Delivery: Command results MUST use the Command Acknowledgment System (pending_acks.json). This guarantees at-least-once delivery, ensuring that if an agent restarts post-execution but pre-confirmation, it will re-send its results upon reboot.

4. Idempotency is a Requirement

Principle: NEVER forget idempotency.

Rationale: We (and our agents) will inevitably run the same command twice. The system must not break or create duplicate state.

Implementation & Contract:

• Install Scripts: Must be idempotent. They MUST check if the agent/service is already installed before trying to install again. This is a core feature.
• Command Design: Future commands should be designed for idempotency. Your research on duplicate commands correctly identifies this as the real fix, not simple de-duplication.
• Database Migrations: All schema changes MUST be idempotent (e.g., CREATE TABLE IF NOT EXISTS, ADD COLUMN IF NOT EXISTS, DROP FUNCTION IF EXISTS).

5. No Marketing Fluff (The "No BS" Rule)

Principle: NEVER use banned words or emojis in logs or code.

Rationale: We are building an "honest" tool for technical users, not pitching a product. Fluff hides meaning and is "enterprise BS."

Implementation & Contract:

• Banned Words: enhanced, enterprise-ready, seamless, robust, production-ready, revolutionary, etc..
• Banned Emojis: Emojis like ⚠️, ✅, ❌ are for UI/comms, not for logs.
• Logging Format: All logs MUST use the [TAG] [system] [component] format. [SECURITY] [agent] [auth] is clear; ⚠️ Agent Auth Failed! ❌ is not.

The Pre-PR Checklist

(This is the practical translation of the ethos. Do not merge until you can check these boxes.)

• All errors logged (not silenced with 2>/dev/null).
• No new unauthenticated endpoints (all use AuthMiddleware).
• Backup/restore/fallback paths for critical operations exist.
• Idempotency verified (can run 3x safely).
• History table logging added for all state changes.
• Security review completed (respects the stack).
• Testing includes error scenarios (not just the "happy path").