# Node.js Scripting Constitution

## 1. Principles
- **Modern Standards:** Use native features introduced in modern Node.js (v18+) over legacy modules or third-party dependencies when possible.
- **Resilience:** All network requests must implement strict timeouts to prevent hanging processes.
- **Simplicity:** Favor clear, readable code using `async/await` over callback-based approaches.
- **Fail-Fast:** Scripts should exit with appropriate status codes immediately upon encountering an unrecoverable error.

## 2. Technical Guidelines
- **HTTP Requests:** Use native `fetch` over the legacy `http` or `https` modules.
- **Timeouts:** Implement timeouts on `fetch` calls using `AbortController`.
- **Exit Codes:** Use `process.exit(0)` for success and `process.exit(1)` for failure.
- **Error Handling:** Use `try/catch` blocks for asynchronous operations. Check `response.ok` as `fetch` does not throw on 4xx/5xx responses.

## 3. Luxury Upgrade 2026 Constraints
- **Zero-Filler Protocol:** Communication must be high-signal (Caveman mode). No pleasantries.
- **Deterministic Verification:** Every code change MUST pass GKE-isolated health checks before PR.
- **Graph-Based Logic:** Swarm tasks follow explicit execution paths. No "best-effort" freeform loops.
- **Context Parsimony:** Every token in session must "earn its place". Lazy-load files; summarize history.
- **Anti-Generic UI:** Frontend output must follow `taste-design` standards (asymmetric, micro-motion, hardware-accelerated).
- **A2A Strictness:** Agents talk via structured MCP/JSON. No fuzzy natural language handoffs.
- **Mandatory Documentation Sync:** Immediately after any code or logic change, update all core documentation and status files (including SWARM_STATUS.md, SWARM_ROADMAP.md, and relevant files under .specify/memory/) to detail what changes were made, their rationale (why and what for), and their design and security implications.

## 4. Official Sources of Truth (Google Tooling Docs)
- **Antigravity CLI (agy):** `https://antigravity.google/docs/getting-started` (the standard for terminal setup and CLI actions).
  - **Встроенная справка:** Использовать `agy --help` для параметров запуска, `agy agent --help` или `agy define_subagent --schema` для схем `settings.json`, и `agy permissions --list` для поддерживаемых экшенов песочницы.
- **Google ADK (Agent Development Kit):** `https://adk.dev/get-started/` & `https://adk.dev/integrations/` (the standard for FastAPI entry points and reasoning engine configurations).
- **gcloud CLI (Google Cloud SDK):** `https://cloud.google.com/sdk/docs/` (the standard for Application Default Credentials and authentication).

## 5. Google Pro Subscription Authentication Constraint
- **Strictly No API Keys**: DO NOT search for, request, or configure Google API keys, Vertex AI billing, or GCP service account credentials for model calls.
- **Strictly OAuth Personal**: The agent swarm and the Telegram bridge MUST use the pre-configured Google Pro personal OAuth subscription (`oauth_creds.json`).
- **No REST/SDK fallback attempts**: Do not try to write Python code to call the Google AI or Vertex AI endpoints directly if they require API keys or billing. Use the `gemini` CLI engine for model orchestration.

## 6. Tooling Priority Matrix (Strict Enforcement)
- **Быстрый факт, погода, новости, пруфы:** Используй `search_web` (Встроенный инструмент, НЕ использовать MCP).
- **Обычный URL (чтение статьи/документации):** Используй `read_url_content` (Встроенный инструмент, НЕ использовать MCP).
- **Глубокое исследование, сбор контекста:** Используй `tavily-search` / `tavily-research` MCP.
- **Поиск компаний, людей, B2B, LinkedIn:** Используй `mcp_exa-mcp_web_search_exa` MCP (category:company/people).
- **Сложный скрейпинг (SPA, JS, авторизация):** Используй `firecrawl-scrape` / `firecrawl-interact` MCP только при крайней необходимости.
- **GitHub URL:** Всегда используй `gh CLI` через терминал. Никогда не используй поиск или веб-скрейпинг.

## 7. Security & Permission Constraints (Plan A)
- **Specs & Plans Write Access:** Subagents have write access to spec/plan files under `/opt/Gemini_Swarm_Core/specs/**` and `/opt/Gemini_Swarm_Core/.specify/**`.
- **Source Code Protection:** Direct modification of source files under `src/**`, `swarm/**`, `scripts/**`, or repository root files is strictly forbidden without manual verification and user confirmation.
- **Spec-Kit SDD Protocol:** All complex changes must follow the `.agents/skills/spec-kit/SKILL.md` workflow: `spec.md` -> `plan.md` -> `tasks.md` -> Explicit User Approval. Direct file modifications to project source code prior to user approval are strictly prohibited.
- **Chat Mode Guard:** When running in conversational chat mode (i.e. `ask_ceo()` prompts), the system automatically injects a `chat_constraint` to run the agent in read-only conversation mode. Auto-execution of file writing tools or modifying shell commands is blocked during strategic discussions unless explicitly commanded.
- **Routine Command Auto-approval:** The following commands are pre-approved to run without triggering manual confirmation:
  - Python scripts and pip installations: `python*`, `pip*`
  - Service status checking: `systemctl status*`
  - Logs reading: `journalctl*`
  - Running tests: `pytest*`
  - Routine frontend builds: `npx*`
- **Branching & Deploy Workflow:** 
  - **Within Antigravity IDE:** Direct commits and pushes to the `main` branch are fully allowed without PRs or manual user merge confirmation, as the IDE serves as the user's direct control center.
  - **Via Telegram Bot:** All development and tasks triggered remotely must go through separate Git branches and PRs for extra validation and safety before being merged to `main` and deployed.
- **VPS Repository Path Rule:** The repository is mapped strictly to `/opt/Gemini_Swarm_Core`. Avoid nested directory duplication.
- **VPS Artifact Storage:** Specification artifacts are stored directly on the VPS for agent access.

## 8. Agent Task Scheduling System
- **Database Queue:** Tasks are tracked dynamically using `swarm_tasks` and `swarm_run_sessions` tables in the VPS SQLite database (`sessions.db`).
- **Daemon Loop:** The `tg-bridge.service` daemon runs a self-contained asyncio scheduling loop. Every 60 seconds, it queries `swarm_tasks` to check if a task is due based on its cron expression and last run time, generating a unique `session_id` for execution tracking.
- **No External Cron Dependencies:** Agents must respect the SQLite-based scheduler architecture. Any new scheduled agent task or change to schedules must be registered as records in the SQLite database rather than external OS level cron jobs.