auth-yes/AGENTS.md

# AGENTS.md — Auth-Yes System Guidelines & Operating Protocol

## 1. Project Context

Auth-Yes is a standalone, ultra-low-friction, zero-trust Identity and Access
Management (IAM) fabric and WebAuthn Passkey authority.

- **Runtime:** Deno 2.x (TypeScript 5.x)
- **Architecture:** Modular Deno Workspace (`sdk/`, `server/`, `ui/`,
  `spire_ffi/`, `infra/`)
- **Web API & SSR:** Hono with pure Hono SSR JSX (Strictly React-free)
- **Workload Mesh:** ConnectRPC daemon + Rust SPIFFE/mTLS FFI crate
  (`spire_ffi/`)
- **Data Layer:** Dedicated PostgreSQL 18 + Valkey 8 (L1/L2 RESP3 Client
  Tracking)
- **Cookie Scope:** Wildcard `.atyg.org` domain scoping with host-collision
  sweep

## 2. Key Architecture Standards

1. **Zero-Dependency SDK:** `@auth-yes/sdk` must remain 100% free of
   backend/database imports. ConnectRPC contracts live in `sdk/gen/`.
2. **Security:** Session invalidation and revocation MUST always be handled
   server-side (`deleteCookie` across host and wildcard domains).
3. **Quality Gates:** Every PR must pass `deno fmt`, `deno task lint`,
   `deno task check`, and `deno test`.
4. **Dual Remote & SDK Distribution:** Development is tracked on GitHub
   (`origin`: `git@github.com:mrteye/auth-yes.git`). All commits and SDK changes
   must be mirrored to Gitea (`gitea`: `git@git.atyg.org:tylerg/auth-yes.git`)
   so that external agents (e.g. Jules) and unauthenticated local projects can
   consume raw SDK modules via
   `https://git.atyg.org/tylerg/auth-yes/raw/branch/main/sdk/mod.ts`.

## 3. Strict Operating Protocol: Methodical Deliberation & Approval Gate

1. **Read-Only First & Deep Context Preservation:**
   - When asked to investigate, audit, analyze, critique, or report, NEVER make
     assumptions or jump directly into modifying files or pushing commits.
   - Spontaneous changes without team alignment break architecture and lose
     context. Always deliberate methodically across at least two levels of
     reasoning before proposing changes.
2. **Mandatory Reporting & Options Presentation:**
   - Inspect files and architecture using read-only tools.
   - Synthesize and present a structured markdown report detailing:
     - Exact state vs. master specification
     - Root causes of discrepancies or missing features
     - Proposed remediation options with trade-offs
3. **Strict Gate on Code Modification:**
   - Offer potential code changes clearly, but NEVER execute edits
     (`write_to_file`, `replace_file_content`) or git commits until the user
     explicitly reviews the proposal and confirms execution.
4. **Standard Task Protocols (`tasks/path.md`):**
   - Follow the standardized engineering lifecycle: `tasks/plan.md`
     $\rightarrow$ `tasks/audit-1.md` $\rightarrow$ `tasks/do.md` $\rightarrow$
     `tasks/audit-2.md`, with `tasks/debug.md` for hermetic root-cause analysis.
5. **Agent Orchestration & Black-Box Delegation:**
   - **Autonomy over Tooling:** When preparing prompts or tasks for external
     agents (e.g., Jules), NEVER micromanage their internal execution mechanics
     or tool choices (e.g. do not prohibit or mandate specific scripting
     languages).
   - **Positive Final-State Delivery:** Define strict terminal Acceptance
     Criteria (clean git working tree, formatted with `deno fmt`, all tests
     passing) rather than negative constraints on in-flight tools.
   - **DRY Instructions:** Rely on repository guideline documents (`AGENTS.md`,
     `tasks/GUIDELINES.md`) by reference rather than copy-pasting operational
     rules into prompts.

## 4. Hypermedia, Datastar & Vertical Feature Slicing Rules

1. **Locality of Behavior (Vertical Slicing):**
   - Co-locate all domain routes, queries, and UI view fragments in
     `src/features/<domain>/`.
   - Name template files `fragments.tsx` or `views.tsx` to reinforce the
     server-side hypermedia model.
2. **Right-Sized Transport Selection:**
   - Standard point-to-point user actions MUST return standard `text/html` JSX
     fragments.
   - SSE streams (`text/event-stream`) are STRICTLY reserved for multi-user
     broadcasts and live pub/sub updates.
   - Abstract SSE protocol strings behind a typed Datastar adapter/SDK. Never
     hand-roll raw SSE strings in route handlers.
3. **Hypermedia Error Invariant & Mid-Stream Resilience:**
   - Never return raw JSON error payloads to browser/Datastar callers.
   - All 4xx validation errors and 5xx server faults MUST return an HTML error
     fragment targeting `#status-banner` or `.field-error`.
   - If an error occurs mid-stream after an SSE connection is open (HTTP 200),
     the handler must yield an error toast fragment before closing cleanly.
4. **Durable State vs. Transient Signals:**
   - Database (PostgreSQL) and Cache (Valkey) are the SOLE authoritative sources
     of state.
   - Datastar `data-signals` must ONLY be used for transient presentation
     toggles (e.g. dropdown open/close). Never cache domain data or store auth
     secrets in client signals.
5. **Vanilla JS Subtree Protection:**
   - Any DOM element manipulated by native browser APIs (WebAuthn passkeys,
     clipboard copy feedback) MUST include `data-ignore` or `data-ignore-morph`
     to prevent Datastar reconciliation conflicts.
6. **Payload & Rate Guardrails:**
   - All interactive action endpoints must be bounded by rate-limiting and a
     strict 16KB request body ceiling.

## 5. AI-Optimized Code Organization & Engineering Principles

1. **Bounded Files & Concise Functions:**
   - Target small, focused functions (4–20 lines) and keep files bounded (under
     300–500 lines) so agents can read, reason, and edit full units in a single
     turn without context fragmentation.
2. **Strict Single Responsibility Principle (SRP):**
   - Every module must do exactly one thing well. Independent modules allow
     agents to isolate and modify code without loading unrelated context.
3. **Flat Call Chains Over Clever DRY Abstractions:**
   - Prefer a flat, shallow 1–2 hop call chain over deep, multi-level
     abstraction hierarchies. Shallow boilerplate is vastly superior to a 5-file
     hop for AI reasoning.
4. **Highly Distinctive, Searchable Naming:**
   - Avoid generic identifiers (`Manager`, `DataHandler`, `process()`). Use
     explicit, searchable domain names (`SessionPinRotator`,
     `streamGuestDrawerTelemetry`, `SessionHandoffCard`).
5. **Deterministic Tooling Enforcement:**
   - All code quality standards must be enforced by automated tooling
     (`deno
     fmt`, `deno task lint`, `deno task check`, `deno test`). Agents
     must verify passing gates before completing tasks.

## 6. History & Context Link

This repository was cleanly extracted from `ed-droid`.

- **Reference Conversation:**
  [Auth-Yes Genesis Transcript](conversation://6a3fa402-ae0a-4231-9991-b0ff79a61e0f)
  (`conversation://6a3fa402-ae0a-4231-9991-b0ff79a61e0f`)