Security & Contribution Guidelines

Relevant source files

The following files were used as context for generating this wiki page:

• CLAUDE.md
• GEMINI.md
• AGENTS.md
• README.md
• conductor/tracks.md
• web/lib/prompts/ucis-v5.1.ts

The Security and Contribution Guidelines for the hex-yt-intel project define the technical standards, architectural laws, and collaborative protocols necessary for maintaining an elite YouTube content synthesis engine. These guidelines ensure that development is consistent across multi-agent sessions and that the hybrid edge infrastructure remains secure and performant.

The project operates under a "Frozen Stack Protocol," utilizing a multi-cloud hybrid flow known as the Hybrid Edge Symphony. Contribution involves adhering to strict file volume constraints, automated verification mandates, and specific coordination patterns managed through shared ledgers.

Sources: CLAUDE.md:1-24, GEMINI.md:14-25, README.md:1-20

Core Security Architecture

The security model of hex-yt-intel relies on a multi-layered verification strategy that spans from request authentication to tamper-proof data persistence.

Hybrid Edge Symphony (ADR 005)

The platform utilizes a multi-cloud architecture to manage security and execution limits:

1. Vercel Bouncer: Acts as a high-security authentication layer and atomic quota enforcer with a ~8s execution window.
2. Cloudflare Streaming: Manages direct browser-to-edge SSE connections for high-latency LLM synthesis tasks (~58s).
3. HMAC Persistence: Implements cryptographically signed server-to-server (S2S) database writes via the /persist endpoint to guarantee data integrity.

Sources: README.md:15-21, CLAUDE.md:12-19, AGENTS.md:23-28

Security Constraints & Policies

The system enforces several "laws" to protect resources and ensure reliability:

• Pre-Query Cache Hit Circuit: Every analysis request must first check the Supabase analyses table to prevent redundant, costly video token processing.
• Stratified Dual-Timeouts: Prevents hanging connections with a 3-second handshake timeout and adaptive streaming windows (25s on Vercel, 90s on Workers).
• Banned Dependencies: Strictly forbids runtime CSS-in-JS engines (Material-UI, Emotion) and next-auth to maintain a high production bundle compression ratio and Edge compatibility.

Sources: CLAUDE.md:4-11, GEMINI.md:31-43

Data Integrity Flow

The following diagram illustrates the secure data flow between the bouncer, the worker, and the persistence layer.

Contribution & Coordination Protocols

Contribution to hex-yt-intel requires strict adherence to multi-agent coordination rules to prevent race conditions and redundant work.

Shared Communication (Agent Ledger)

All contributors (human or agent) MUST utilize the .memory/AGENT_LEDGER.md protocol:

1. Read: Review the ledger before starting any task to ensure no other agent is modifying the same files.
2. Intent: Log an [IN_PROGRESS] entry with target files and timestamp.
3. Completion: Update the entry to [DONE] when the task is finished and verified.

Sources: CLAUDE.md:21-31, AGENTS.md:42-49

The Orchestrator "Sink" Pattern

For complex workflows (e.g., PR reviews or major refactors), an agent must claim the "Sink" role:

• Sink Orchestrator: Responsible for the end-to-end lifecycle, including branch creation, sub-task delegation, final testing, and merging.
• Assisting Agents: Execute sub-tasks but are restricted from finalizing or merging the overarching workflow.

Sources: CLAUDE.md:27-31, AGENTS.md:51-57

File Volume & Taxonomy

The project enforces a strict limit of exactly 4 Markdown files in the root directory:

1. CLAUDE.md (Infrastructure Spec)
2. GEMINI.md (Multi-Agent Directives)
3. README.md (Project Overview)
4. AGENTS.md (Identity & Workflows)

All other documentation must be nested within the /docs/ subdirectories.

Sources: GEMINI.md:45-49, conductor/tracks.md:13-16

Engineering Standards

Frozen Stack Protocol

Development must be performed using the pinned versions of the infrastructure stack:

Technology	Version	Usage
Node.js	24.16.0 LTS	Primary runtime
pnpm	11.1.3	Workspace package management
Next.js	16.2.6	Frontend & Bouncer framework
TypeScript	5.6.2	Strict type safety
Tailwind CSS	Latest	Exclusive styling framework

Sources: GEMINI.md:21-30, CLAUDE.md:40-49

Preflight Verification Mandate

Before applying any mutation, agents must perform a "10x Verification" to confirm if the issue persists or if a sibling agent has already implemented the fix.

// Example Preflight Logic derived from GEMINI.md
const preflight = async (file: string, pattern: string) => {
  const diff = await exec(`git diff HEAD ${file}`);
  if (diff.includes(pattern)) {
    console.log('Fix already applied by sibling agent');
    return false;
  }
  return true;
};

Sources: GEMINI.md:73-100

Content Intelligence Integrity (UCIS v5.1)

Contributions to the analysis engine must adhere to the Transcript Absolutism directive. This is the highest-priority constraint for the Ultimate Content Intelligence & Implementation System (UCIS):

• Closed Universe: The system must operate as a "blind, ruthless parser," using ONLY the provided transcript.
• No Inference: External data enrichment, web searching, or hallucinations are strictly forbidden.
• Insufficient Data Protocol: If a dimension cannot be fulfilled from the transcript, the output must explicitly state [Insufficient data in source transcript to fulfill this dimension].

Sources: web/lib/prompts/ucis-v5.1.ts:25-50, supabase/migrations/20260611142500_add_prompt_config.sql:24-45

Summary

The Security & Contribution Guidelines of hex-yt-intel prioritize architectural stability and coordination integrity. By leveraging the Hybrid Edge Symphony for secure streaming and the Agent Ledger for concurrent development, the project maintains a high-performance environment that is resilient to timeouts and data corruption. All contributors are expected to uphold the Frozen Stack Protocol and the strict Transcript Absolutism that defines the core value of the content synthesis engine.