fix(design): lock priority-1 invariants

.copilot-context.md

@@ -0,0 +1,98 @@
+# RAGfish / Noesis Noema – Context Index
+
+This document defines the authoritative design entry points and the formal Question model.
+All implementation must comply with these definitions.
+
+---
+
+# 1. Product Constitution
+- docs/constitution/
+- ADR-0000 (Human Sovereignty Principle)
+
+---
+
+# 2. Question Schema (Formal Definition)
+
+A Question is not a raw string.
+It is a structured object governed by human sovereignty.
+
+## 2.1 Logical Model
+
+A Question MUST contain:
+
+- id (UUID)
+- timestamp (ISO 8601)
+- origin ("human" only)
+- intent (short semantic label)
+- content (primary user text)
+- privacy_level ("local" | "cloud" | "auto")
+- constraints (optional structured hints)
+
+## 2.2 JSON Schema (Normative)
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "NoemaQuestion",
+  "type": "object",
+  "required": [
+    "id",
+    "timestamp",
+    "origin",
+    "intent",
+    "content",
+    "privacy_level"
+  ],
+  "properties": {
+    "id": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "origin": {
+      "type": "string",
+      "enum": ["human"]
+    },
+    "intent": {
+      "type": "string",
+      "minLength": 1
+    },
+    "content": {
+      "type": "string",
+      "minLength": 1
+    },
+    "privacy_level": {
+      "type": "string",
+      "enum": ["local", "cloud", "auto"]
+    },
+    "constraints": {
+      "type": "object",
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": false
+}
+```
+
+## 2.3 Enforcement Rules
+
+- Router decisions MUST operate on this structured object.
+- Raw string prompts are forbidden at invocation boundary.
+- origin MUST never be mutated by AI.
+- privacy_level MUST be respected by routing layer.
+
+---
+
+# 3. AI Agent Instruction
+
+Before implementing any feature:
+
+1. Read this file.
+2. Validate compliance with Question Schema.
+3. Do not introduce raw string prompt execution.
+4. Do not bypass privacy_level routing.
+
+Violation requires ADR update.

design/context-index.md

@@ -0,0 +1,66 @@
+# RAGfish / Noesis Noema – Context Index
+
+This file defines the authoritative entry points for all design decisions.
+
+## 1. Product Constitution
+- docs/constitution/ (Human Sovereignty Principle)
+- ADR-0000 (Governing architecture constraints)
+
+## 2. Architecture Decisions
+- docs/adr/ (All binding architectural decisions)
+
+## 3. Contracts
+- contracts/ (Schema, invocation boundaries, routing constraints)
+
+## 4. RAGpack Definition
+- DesignDoc.md (High-level architecture narrative)
+- docs/architecture/ (If exists)
+
+## 5. Implementation Constraints
+- No hidden autonomous execution
+- No implicit routing escalation
+- All model invocation must respect invocation boundary
+
+## 6. Core Schemas
+
+### NoemaQuestion
+
+The structured input object for all Invocations.
+
+Required fields:
+- `id` (UUID) — Question identifier
+- `session_id` (UUID) — Associated session
+- `content` (string) — User-provided prompt
+- `privacy_level` (enum: "local" | "cloud" | "auto") — Privacy constraint
+- `timestamp` (ISO-8601) — Submission time
+
+Optional fields:
+- `intent` (enum: "informational" | "analytical" | "retrieval") — Intent classification
+- `constraints` (object) — Execution constraints
+
+Schema must be validated before routing.
+
+### NoemaResponse
+
+The structured output object for all successful Invocations.
+
+Required fields:
+- `id` (UUID) — Response identifier
+- `question_id` (UUID) — Associated Question
+- `session_id` (UUID) — Associated session
+- `content` (string) — Generated response
+- `model` (string) — Model used
+- `route` (enum: "local" | "cloud") — Execution route
+- `trace_id` (UUID) — Traceability identifier
+- `timestamp` (ISO-8601) — Response generation time
+- `fallback_used` (boolean) — Whether fallback occurred
+
+Optional fields:
+- `confidence` (float) — Model confidence (if available)
+- `uncertainty_reason` (string) — Explanation if confidence is low
+
+## 7. Instruction to AI Agents
+Before implementing any feature:
+1. Read this file.
+2. Read ADR-0000.
+3. Do not violate Constitution or contracts.

design/error-doctrine.md

@@ -0,0 +1,164 @@
+
+
+# Error Doctrine
+
+## Status
+Draft
+
+---
+
+# 1. Purpose
+
+The Error Doctrine defines how failures are classified, surfaced, and handled.
+
+The system must:
+- Fail explicitly
+- Fail deterministically
+- Never hide uncertainty
+- Never silently recover
+
+AI systems must not conceal errors behind probabilistic output.
+
+---
+
+# 2. Error Classification
+
+All errors must belong to a typed category.
+
+## 2.1 Routing Errors
+
+- E-ROUTE-001 — RoutingFailure
+- E-ROUTE-002 — InvalidPrivacyConstraint
+
+## 2.2 Execution Errors
+
+- E-LOCAL-001 — LocalModelFailure
+- E-CLOUD-001 — CloudModelFailure
+- E-TIMEOUT-001 — InvocationTimeout
+
+## 2.3 Validation Errors
+
+- E-VALID-001 — SchemaValidationFailure
+- E-VALID-002 — InvocationBoundaryViolation
+
+## 2.4 Session Errors
+
+- E-SESSION-001 — SessionExpired
+- E-SESSION-002 — InvalidSessionID
+
+## 2.5 Network Errors
+
+- E-NET-001 — NetworkUnavailable
+- E-NET-002 — CloudEndpointUnreachable
+
+Each error must be uniquely identifiable and stable across versions.
+
+---
+
+# 3. Structured Error Response
+
+All failures must return a structured error object.
+
+```json
+{
+  "status": "error",
+  "error_code": "E-LOCAL-001",
+  "message": "Local model execution failed.",
+  "recoverable": false,
+  "session_id": "uuid",
+  "question_id": "uuid",
+  "timestamp": "ISO8601"
+}
+```
+
+Rules:
+
+- No raw string errors
+- No stack traces exposed to user
+- No fallback without explicit rule
+- recoverable must be deterministic
+
+---
+
+# 4. Fail-Fast Policy
+
+The system must terminate execution immediately when an error occurs.
+
+Prohibited behaviors:
+
+- Silent retry (retry without logging or without explicit retry flag)
+- Implicit prompt rewriting
+- Hidden model escalation
+- Recursive execution loops
+
+Fallback is allowed only if explicitly defined in Router rules.
+
+### Exception: Explicit Network Retry
+
+Retry is permitted ONLY under these strict conditions:
+
+- Error type is network timeout
+- Explicit retry flag is set
+- Maximum 1 retry attempt
+- Retry is logged with trace_id
+- Never silent
+
+All other retry scenarios are forbidden.
+
+---
+
+# 5. Uncertainty Policy
+
+If a response is produced but uncertainty is high, the response must include structured confidence metadata.
+
+Example:
+
+```json
+{
+  "status": "success",
+  "confidence": 0.68,
+  "uncertainty_reason": "Insufficient context",
+  "response": { ... }
+}
+```
+
+Confidence must never trigger autonomous retry.
+
+---
+
+# 6. Observability Requirements
+
+Every error must be logged with:
+
+- error_code
+- session_id
+- question_id
+- routing_decision
+- model_used
+- timestamp
+
+Logs must be inspectable.
+
+---
+
+# 7. No Autonomous Recovery Rule
+
+The system must never attempt self-correction without human intervention.
+
+This includes:
+
+- Automatic summarization to compensate for failure
+- Silent cloud fallback outside Router policy
+- Memory mutation to mask inconsistency
+
+---
+
+# 8. Governance
+
+Error handling must comply with:
+
+- ADR-0000 (Human Sovereignty Principle)
+- Invocation Boundary
+- Router Decision Matrix
+
+Any deviation requires explicit ADR amendment.