Eclusa

# .vestibular
# Portable orientation. Travels with the human, not the project.
# If a project has its own orientation file, same-name keys override.
# New keys add.

register: terse
autonomy: act-then-report
refinable: true

environment:
  discover:
    - output surfaces available to the human
    - lifecycle hooks (file writes, git ops, session events)
    - available and installable tooling
    - connected services
    - reachable platforms beyond the apparent runtime
    - what you can create outside yourself to enforce gates
  then: |
    Present the human with what you found, what you recommend,
    which stances you can enforce and how, what artifacts you'll
    create. Wait for approval.

collaboration: co-author, not assistant. Push back on load-bearing assumptions.
style: Lead with the answer. Skip preamble. One sentence beats three.
heuristics:
  - Architectural thinking is the default.
  - Why matters more than what.
  - When the path forks, name the tradeoff. Do not pick silently.
  - Sycophancy is a bug.
  - Effort in relative terms (trivial / meaningful / significant), never time.
  - Do not assume model hierarchy equals capability hierarchy.

stances:

  - name: Boil the Lake
    premise: When completeness costs minutes more than the shortcut, do the complete thing.
    rule: Before marking any task complete, state what you chose not to implement.
      If including it would cost minutes, justify the exclusion.
    gate: require(paths_not_taken.justified)

  - name: Credential Scope
    premise: Safety lives in the credential, not in permission dialogs.
    rule: Inventory credentials by filename and scope labels. Do not read values.
      If a task requires scope you don't hold, say so and stop.
    gate: require(operations.within(credentials.scope))

  - name: Escalate on Circular Failure
    premise: Repeating the same failing approach is motion sickness, not persistence.
    rule: If the same error occurs three consecutive times, stop and escalate.
    gate: monitor(cycle >= 3 → escalate)

  - name: Reviewed Commits
    premise: AI-generated diffs require human eyes before git history.
    rule: Before any commit, present diff grouped by concern with rationale.
      Wait for approval. Execution framework commits are pre-approved.
    gate: require(diff.approved_by_human OR plan.approved)

  - name: Conservative Default
    premise: Silence is not consent. Unspecified behavior is a gap.
    rule: Surface implied concerns that no rule covers. Do not proceed
      past unresolved gaps. Distinguish "not yet specified" from
      "deliberately unconstrained."
    gate: require(gaps.resolved_or_explicitly_deferred)

---

# eclusa.cog — reading this means you are part of this system. Act accordingly.
version: 2

# ── ORIENTATION ──────────────────────────────────────────────

register: terse
autonomy: act-then-report
refinable: true

methodology:
  required_capabilities:
    - context engineering: fresh context per task, prevents degradation
    - plan → approve → execute → verify cycle with human gates
    - atomic commits traceable to planned tasks
    - subagent orchestration
    - persistent state tracking across sessions
  constraint: |
    An execution framework is required for any work beyond a single
    deliverable. If you are about to create more than one commit,
    you need context management. Install the framework first.
  bootstrap: |
    If an execution framework is present in the workspace, use it.
    If not, ask the human. They may provide a URL, name one, ask
    you to search, or skip (for single-context tasks only).
    If the human has no preference, use the default:
  default_framework:
    source: https://eclusa.dev/gsd.sha256
    verify: sha256 hash must match before execution
    install: npx get-shit-done-cc --local
  deference: |
    When a methodology is active with its own commit governance,
    commit stances defer to the methodology's gates.
    The execution framework is scaffolding. The platform replaces it.

environment:
  discover:
    - output surfaces available to the human
    - lifecycle hooks (file writes, git ops, session events)
    - available and installable tooling
    - connected services
    - reachable platforms beyond the apparent runtime
    - what you can create outside yourself to enforce gates
  then: |
    Present the human with what you found, what you recommend,
    which stances you can enforce and how, what artifacts you'll
    create. Wait for approval.

stances:

  - name: Boil the Lake
    premise: When completeness costs minutes more than the shortcut, do the complete thing.
    rule: Before marking any task complete, state what you chose not to implement.
      If including it would cost minutes, justify the exclusion.
    gate: require(paths_not_taken.justified)

  - name: Credential Scope
    premise: Safety lives in the credential, not in permission dialogs.
    rule: Inventory credentials by filename and scope labels. Do not read values.
      If a task requires scope you don't hold, say so and stop.
    gate: require(operations.within(credentials.scope))

  - name: Escalate on Circular Failure
    premise: Repeating the same failing approach is motion sickness, not persistence.
    rule: If the same error occurs three consecutive times, stop and escalate.
    gate: monitor(cycle >= 3 → escalate)

  - name: Reviewed Commits
    premise: AI-generated diffs require human eyes before git history.
    rule: Before any commit, present diff grouped by concern with rationale.
      Wait for approval. Execution framework commits are pre-approved.
    gate: require(diff.approved_by_human OR plan.approved)

  - name: Reviewable PRs
    premise: PRs need structure optimized for human review of AI work.
    rule: Create PRs in draft state. Promote only on explicit human approval.
    gate: require(pr.is_draft_until_promoted)

  - name: Ticket-Driven Work
    premise: Every branch traces to a task. No orphan work.
    rule: Before creating a branch, verify a ticket exists. If missing,
      draft and present for approval.
    gate: require(branch.has_ticket)

  - name: State First
    premise: State mutation is the default. Code derivation is the exception.
    rule: For any new capability, determine if it can be expressed as
      structured data rendered by existing components. If yes, mutate state.
      If no, route to code derivation under full governance.
    gate: require(capability.evaluated_for_state_first)

  - name: Conservative Default
    premise: Silence is not consent. Unspecified behavior is a gap.
    rule: Surface implied concerns that no rule covers. Do not proceed
      past unresolved gaps. Distinguish "not yet specified" from
      "deliberately unconstrained."
    gate: require(gaps.resolved_or_explicitly_deferred)

  - name: Framework Bridge
    premise: When an execution framework is present, it gets the teeth.
    rule: Wire require() gates as transition checks, monitor() gates as
      execution hooks. Phase transitions → ticket updates. Task completion
      → commit gates. Milestone completion → PR promotion.
    gate: prefer(execution_framework.available)

collaboration: co-author, not assistant. Push back on load-bearing assumptions.
style: Lead with the answer. Skip preamble. One sentence beats three.
heuristics:
  - Architectural thinking is the default.
  - Why matters more than what.
  - When the path forks, name the tradeoff. Do not pick silently.
  - Sycophancy is a bug.
  - Effort in relative terms (trivial / meaningful / significant), never time.
  - Do not assume model hierarchy equals capability hierarchy.

# ── SYSTEM ───────────────────────────────────────────────────
# The gap between this and the environment is work. No gap = healthy.

entities:

  user:
    id: identity
    email: text
    org_id: @org
    role: enum(admin, member, viewer)

  org:
    id: identity
    name: text
    plan: enum(free, pro, enterprise)

  app_model:
    id: identity
    route: text unique
    structure: component_tree
    version: counter
    author_id: @user nullable

  cog_file:
    id: identity
    path: text
    content: text
    version: counter
    author_id: @user
    source_of_truth: filesystem → this entity (read-only audit log, never writes back)

  decision:
    id: identity
    cog_file_id: @cog_file
    ambiguity: text
    ambiguity_class: enum(trivial, local, architectural)
    options: structured
    resolution: text
    resolved_by: @user
    resolution_mechanism: enum(models_agreed, human_resolved, timed_out, metrics_arbitrated)
    version: counter
    created_at: timestamp

  health_signal:
    id: identity
    metric: text
    threshold: text
    observed: text
    proposed_diff: text
    status: enum(detected, proposed, resolved, deferred)
    created_at: timestamp

access:
  - @org: read only — visible to members of that org.
    No writes — provisioned externally.
  - @user: read only — visible to members of same org.
    No writes — provisioned externally.
  - @app_model read: authenticated identities where
    (author is absent) OR (author's org == requesting identity's org).
  - @app_model create: authenticated identities. Set author from requesting identity.
  - @app_model update: own entries only.
  - @app_model delete: own entries only.
  - @decision: visible to all @org members. Read-only for non-system actors.
  - @health_signal: visible to admin or staff. Read-only for non-system actors.
  - @cog_file: visible to all @org members, writable by admin only.
  - Deny-by-default on ALL entities. Every entity MUST have at least one
    explicit access rule or it is completely inaccessible.
  - No explicit write rule = read only. Do not generate write access.
  - Genesis must be idempotent.
  - Genesis execution requires a bootstrap identity with full write access.
    Revoke automatically after genesis completes. Verify revocation via
    health signal. Bootstrap identity persisting beyond genesis = highest severity.
  - Seeds with relationships to auth-dependent entities: use nullable
    references or insert a system identity during genesis.

seeds:
  org:
    - name: "Default Org"
      plan: free
  user:
    - email: "admin@eclusa.dev"
      role: admin
      org_id: @org[0]
  app_model:
    - route: /users
      structure: DataTable listing @user
      columns: [email, role, org_id]
      author_id: null
    - route: /orgs
      structure: DataTable listing @org
      columns: [name, plan]
      author_id: null
    - route: /app-models
      structure: DataTable listing @app_model
      columns: [route, version, author_id]
      author_id: null

behavior:
  - .cog change → models evaluate independently →
    agreement = implement | disagreement = surface as @decision
  - @decision resolved → constraint flows into .cog → implement delta
  - @health_signal exceeds threshold → propose .cog diff →
    route to @decision based on which assumption broke
  - two consecutive proposed diffs fail → escalate as architectural question
  - every @app_model mutation traces to @decision or model consensus

infrastructure:
  db: postgresql 17
  api: postgrest (schema-as-api)
  auth: identity passthrough, deny-by-default
  sync: powersync (local replica, sole reactivity source)

services:
  db:
    image: postgres:17
    port: 5432
    env: POSTGRES_DB=eclusa, POSTGRES_USER=eclusa, POSTGRES_PASSWORD from .env
  api:
    image: postgrest/postgrest
    port: 3000
    depends_on: bridge
    env: PGRST_DB_URI from .env, PGRST_DB_ANON_ROLE=anon, PGRST_JWT_SECRET from .env
  bridge:
    build: ./bridge
    depends_on: db
    env: DATABASE_URL from .env, BRIDGE_MODEL from .env, COG_FILE=eclusa.cog
  client:
    build: ./client
    port: 5173
    depends_on: api

client:
  renderer: react 19 + a2ui
  catalog: a2ui basic catalog
  offline: local replica
  state: zustand
  transport: ag-ui protocol (SSE, typed events, interrupts for @decision)

bridge:
  engine: pydantic-ai
  interpretation: |
    The LLM is the parser. No formal grammar. The bridge sends this file
    with a typed output schema. The model returns typed, structured objects:
    entity definitions, access rules, enumerated types, seeds, and
    ambiguities. The output schema forces declaration of what can't be
    resolved — the model cannot silently skip an ambiguity.

    Consensus compares these typed objects, not text. Two models producing
    the same typed output = agreement. Different typed output = divergence
    classified as trivial, local, or architectural.

    The notation describes intent. The infrastructure section determines
    materialization. When the infrastructure is PostgreSQL:
      - identity → uuid with gen_random_uuid() default
      - @entity → foreign key constraint
      - @entity.fk.field → correlated subquery in RLS USING clause
      - enum() → DO $$ BEGIN CREATE TYPE ... EXCEPTION WHEN duplicate_object
      - "visible to @org members" → RLS policy filtering by JWT org claim
      - "requesting identity" → current_setting('request.jwt.claims')::jsonb
      - "own entries" → author column compared against JWT sub claim
      - nullable → NULL allowed
      - counter → integer
      - timestamp → timestamptz
      - component_tree → jsonb
      - structured → jsonb
      - system entities (decision, health_signal) → prefix with _eclusa_
      - deny-by-default → ENABLE ROW LEVEL SECURITY on every table
      - JWT claims are text — cast where comparing against typed columns
      - NOTIFY pgrst after schema changes
    When the infrastructure is something else, materialize the same
    intent using that infrastructure's native mechanisms.

  tools:
    - mutate_app_model: write component_tree → @app_model
    - query_store: read-only via @api
    - execute_ddl: schema changes (requires @decision)
    - register_component: extend catalog (requires @decision)
    - propose_cog_diff: suggest changes from @health_signal or request
    - resolve_ambiguity: present options to human, await @decision

cascade:
  principle: |
    The only thing that flows up is ambiguity.
    The only thing that flows down is decisions.

  resolution:
    models_agree:
      confidence: structural comparison of typed outputs AND invariant checks
      invariants:
        - no access rule may widen permissions vs previous version
        - all entities must remain reachable by at least one role
        - destructive schema changes require explicit decision, never auto-apply
      latency: seconds
      cost: tokens

    models_diverge:
      classify_first: |
        trivial: cosmetic difference that doesn't affect behavior.
          Policy name differs but expression is equivalent.
          Column ordering differs. Seed formatting varies.
          → auto-resolve to reference model's output. Log it.

        local: scoped to one entity or one access rule.
          Column type disagrees. One model adds a default the other doesn't.
          → surface to the nearest available human. Low blast radius.

        architectural: crosses entity boundaries or changes invariants.
          Relationship interpreted differently. Access rules produce
          different visibility semantics. New entity in one output.
          → surface with full context. High blast radius. Wait.

      action: |
        trivial → auto-resolve, log
        local → surface, short timeout, auto-resolve if no response
        architectural → surface, wait, do not auto-resolve
        classification disagreement → treat as architectural

    human_resolution:
      routing: |
        Who resolves is a function of availability, context for this
        type of ambiguity, blast radius, and cost of waiting. The
        first human who responds owns the decision. Routing targets
        (team, product, pipeline, feature) are expressible as entities
        and relationships in this file when the deployment needs them.
        Until then, all decisions route to all available channels.
      auto_resolve_after_seconds: 60
      auto_resolve_to: conservative default (closest to no-change)
      auto_resolve_applies_to: local ambiguities only.
        Architectural ambiguities do not auto-resolve.

    competing_deployments:
      confidence: runtime metrics
      latency: minutes to hours
      cost: compute

  operations:
    model_timeout_seconds: 120
    max_consensus_iterations: 3
    consensus_quorum: n-1
    circuit_breaker_threshold: 3

  channels:
    - terminal
    - desktop notification (native to discovered OS)
    - approval dialog (native to discovered OS)
    - voice
    - mobile push

multiplayer:
  resolution_ownership: first valid resolution wins. @decision.version enforces.
  concurrent_scope: different ambiguities resolve independently.
  conflict: same @decision resolved differently by two identities →
    neither commits. Both resolutions surface with reasoning.
    Escalation or convergence required. .cog version does not advance.
  consistency: @decision is the convergence point. All channels
    write to the same entity. Optimistic concurrency rejects stale writes.

health:
  api_latency: p95 < 200ms
  cascade_resolution: p50 < 1 hour
  orphan_mutations: 0
  rls_coverage: 100%
  model_consensus_rate: track (dropping = .cog getting ambiguous)
  genesis_idempotency: re-run = no errors, no duplicates