docs: establish ELUNVERA product and technical baseline

.coderabbit.yaml

@@ -0,0 +1,7 @@
+reviews:
+  auto_review:
+    enabled: true
+    base_branches:
+      - main
+      - develop
+  review_status: true

.cwl/data-management.yaml

@@ -0,0 +1,48 @@
+schema_version: '1.0'
+repository: ContextualWisdomLab/ELUNVERA
+product_name: ELUNVERA
+authoritative_data_assets:
+  - asset_code: customer_relationship_record
+    description: Tenant-scoped parties, accounts, roles, relationships, evidence, and history.
+    data_classification: restricted_personal_and_commercial
+    system_of_record: true
+  - asset_code: commercial_opportunity_record
+    description: Opportunity process, stage, value, forecast, stakeholder, and outcome history.
+    data_classification: confidential_commercial
+    system_of_record: true
+  - asset_code: complaint_outcome_record
+    description: Complaint, remedy, customer response, satisfaction observation, and outcome history.
+    data_classification: restricted_customer_case
+    system_of_record: true
+data_owner_role: elunvera_product_owner
+data_steward_role: tenant_data_steward
+critical_data_elements:
+  - party_identity_reference
+  - relationship_truth_status
+  - relationship_valid_time
+  - account_owner_assignment
+  - opportunity_stage_history
+  - monetary_amount_and_currency
+  - communication_preference
+  - complaint_status
+quality_rule_references:
+  - docs/DATA_MODEL.md#18-data-quality-invariants
+  - docs/TEST_STRATEGY.md
+retention_policy_references:
+  - docs/PRIVACY.md#8-retention-and-disposition
+  - docs/adr/0015-retention-disposition.md
+lineage_producers:
+  - elunvera_api
+  - elunvera_worker
+lineage_consumers:
+  - semantic_data_portal
+  - lineageweave
+applicable_knowledge_areas:
+  - data_governance
+  - data_quality
+  - metadata_management
+  - data_security
+  - data_integration_and_interoperability
+assessment_exclusions:
+  - code: production_runtime_evidence
+    reason: The repository baseline contains no implemented runtime.

.github/pull_request_template.md

@@ -0,0 +1,38 @@
+## Product outcome
+
+Describe the buyer- or operator-visible problem closed by this PR.
+
+## Scope and boundaries
+
+- Owning ELUNVERA responsibility:
+- CWL dependencies consumed by contract:
+- Explicitly excluded work:
+
+## Evidence
+
+- Exact head:
+- Tests and commands actually run:
+- Coverage and documentation denominators:
+- Migration/restore/security/accessibility/model evidence, where applicable:
+
+## Data and privacy
+
+- Data assets and classifications changed:
+- Tenant, purpose, retention, legal-hold, and export impacts:
+- New event fields reviewed for PII/secrets:
+
+## Contracts and docs
+
+- [ ] OpenAPI/AsyncAPI/JSON Schema updated
+- [ ] ADR updated or decision remains conformant
+- [ ] `docs/product-technical-gap-baseline.md` updated
+- [ ] `CHANGELOG.md` updated
+- [ ] Doctoring and references updated
+
+## Review gate
+
+- [ ] Current-head checks complete
+- [ ] Independent approval received
+- [ ] Unresolved threads are zero
+- [ ] No queued/pending/skipped check is represented as successful
+- [ ] One-shot/self-modifying workflow removed after its purpose

.github/workflows/document-contracts.yml

@@ -0,0 +1,200 @@
+name: document-contracts
+
+on:
+  pull_request:
+    branches:
+      - main
+      - develop
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: document-contracts-${{ github.repository }}-${{ github.event.pull_request.number || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Check out exact revision
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # actions/checkout@v7
+        with:
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
+          persist-credentials: false
+
+      - name: Verify exact checkout
+        env:
+          EXPECTED_SHA: ${{ github.event.pull_request.head.sha || github.sha }}
+        run: test "$(git rev-parse HEAD)" = "$EXPECTED_SHA"
+
+      - name: Validate document and schema contracts
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          ruby -ryaml - <<'RUBY'
+          methods = %w[get post put patch delete options head trace]
+          openapi = YAML.safe_load(File.read('schemas/openapi.yaml'), aliases: false)
+          raise 'OpenAPI version mismatch' unless openapi['openapi'] == '3.2.0'
+          operations = []
+          openapi.fetch('paths').each do |path, item|
+            item.each do |method, operation|
+              next unless methods.include?(method)
+              operations << [method.upcase, "/v1#{path}", operation.fetch('operationId')]
+            end
+          end
+          expected = [
+            ['GET', '/v1/accounts'],
+            ['POST', '/v1/accounts'],
+            ['GET', '/v1/accounts/{account_id}'],
+            ['PATCH', '/v1/accounts/{account_id}'],
+            ['POST', '/v1/relationships'],
+            ['POST', '/v1/opportunities/{opportunity_id}/stage-transitions']
+          ].sort
+          raise 'OpenAPI P0 operation mismatch' unless operations.map { |method, path, _| [method, path] }.sort == expected
+          raise 'duplicate operationId' unless operations.map(&:last).uniq.length == operations.length
+
+          ['/accounts', '/accounts/{account_id}'].each do |path|
+            operation = openapi.fetch('paths').fetch(path).fetch('get')
+            refs = operation.fetch('parameters').filter_map { |parameter| parameter['$ref'] }
+            %w[ValidAt RecordedAt KnowledgeCutoff].each do |name|
+              raise "missing temporal parameter #{name}" unless refs.include?("#/components/parameters/#{name}")
+            end
+            headers = operation.fetch('responses').fetch('200').fetch('headers')
+            %w[X-ELUNVERA-Valid-At X-ELUNVERA-Recorded-At X-ELUNVERA-Knowledge-Cutoff].each do |name|
+              raise "missing temporal response header #{name}" unless headers.key?(name)
+            end
+          end
+
+          asyncapi = YAML.safe_load(File.read('schemas/asyncapi.yaml'), aliases: false)
+          raise 'AsyncAPI version mismatch' unless asyncapi['asyncapi'] == '3.1.0'
+          raise 'event producer direction mismatch' unless asyncapi.fetch('operations').values.all? { |operation| operation['action'] == 'send' }
+          envelope = asyncapi.fetch('components').fetch('schemas').fetch('CloudEventEnvelope')
+          %w[dataclassification schemarevision provenanceref].each do |name|
+            raise "missing required event metadata #{name}" unless envelope.fetch('required').include?(name)
+          end
+          provenance = envelope.fetch('properties').fetch('provenanceref')
+          raise 'provenance must be a non-null string' unless provenance['type'] == 'string'
+          raise 'provenance must reject empty values' unless provenance['minLength'].to_i >= 1
+
+          coderabbit = YAML.safe_load(File.read('.coderabbit.yaml'), aliases: false)
+          review_bases = coderabbit.fetch('reviews').fetch('auto_review').fetch('base_branches')
+          raise 'CodeRabbit must review canonical main PRs' unless review_bases.include?('main')
+          RUBY
+
+          python - <<'PY'
+          import hashlib
+          import json
+          import re
+          import subprocess
+          from pathlib import Path
+          from urllib.parse import unquote
+
+          required = {
+              Path('docs/PRD.md'),
+              Path('docs/TRD.md'),
+              Path('docs/ARCHITECTURE.md'),
+              Path('docs/DATA_MODEL.md'),
+              Path('docs/API_CONTRACT.md'),
+              Path('docs/product-technical-gap-baseline.md'),
+              Path('docs/adr/README.md'),
+              Path('schemas/openapi.yaml'),
+              Path('schemas/asyncapi.yaml'),
+          }
+          missing = sorted(str(path) for path in required if not path.is_file())
+          assert not missing, missing
+
+          branch_markers = {
+              Path('AGENTS.md'): 'Use canonical protected `main` as the ordinary product base.',
+              Path('CONTRIBUTING.md'): 'Base ordinary product work on canonical protected `main`',
+              Path('docs/PRD.md'): '- **Primary branch:** `main`',
+              Path('docs/ROADMAP.md'): '`main` integration branch and protected review policy established.',
+              Path('docs/superpowers/plans/2026-08-27-elunvera-foundation-implementation-plan.md'): 'The ordinary integration base is canonical protected `main`',
+              Path('docs/superpowers/specs/2026-08-27-elunvera-product-technical-baseline-design.md'): 'through canonical protected `main`',
+          }
+          for path, marker in branch_markers.items():
+              assert marker in path.read_text(encoding='utf-8'), f'canonical-main authority drift: {path}'
+
+          product_contract_markers = {
+              Path('docs/PRD.md'): (
+                  'p95 ≤ 20 ms',
+                  'Korean, English, Japanese, Chinese, Vietnamese, Spanish, German, and French',
+                  'DB-backed, versioned translation resources',
+              ),
+              Path('docs/TRD.md'): (
+                  'server/native clients fetch and cache only the screen keys they need',
+                  'p95 ≤ 20 ms',
+              ),
+              Path('docs/UX_SPEC.md'): (
+                  'Korean, English, Japanese, Chinese, Vietnamese, Spanish, German, and French',
+                  'DB-backed, versioned translation resources',
+              ),
+              Path('docs/TEST_STRATEGY.md'): (
+                  'p95 ≤ 20 ms',
+                  'ko/en/ja/zh/vi/es/de/fr',
+              ),
+          }
+          for path, markers in product_contract_markers.items():
+              text = path.read_text(encoding='utf-8')
+              for marker in markers:
+                  assert marker in text, f'commercialization contract drift: {path}: {marker}'
+
+          for event_path in (
+              Path('schemas/events/relationship-changed-v1.schema.json'),
+              Path('schemas/events/opportunity-stage-changed-v1.schema.json'),
+          ):
+              schema = json.loads(event_path.read_text(encoding='utf-8'))
+              assert schema['$schema'] == 'https://json-schema.org/draft/2020-12/schema'
+              assert schema['additionalProperties'] is False
+              assert 'recorded_at' in schema['required']
+              assert schema['properties']['recorded_at']['format'] == 'date-time'
+
+          manifest = json.loads(Path('manifest.json').read_text(encoding='utf-8'))
+          tracked = {
+              path
+              for path in subprocess.check_output(
+                  ['git', 'ls-files'], text=True
+              ).splitlines()
+              if path != 'manifest.json'
+          }
+          entries = {entry['path']: entry for entry in manifest['files']}
+          assert manifest['self_excluded'] is True
+          assert manifest['file_count'] == len(entries) == len(tracked)
+          assert set(entries) == tracked
+          for path_text, entry in entries.items():
+              path = Path(path_text)
+              payload = path.read_bytes()
+              assert hashlib.sha256(payload).hexdigest() == entry['sha256'], path
+              assert len(payload) == entry['size_bytes'], path
+              assert len(payload.decode('utf-8').splitlines()) == entry['line_count'], path
+
+          link_pattern = re.compile(r'(?<!!)\[[^\]]*\]\(([^)]+)\)')
+          for markdown_path in sorted(Path('.').rglob('*.md')):
+              in_fence = False
+              fence_count = 0
+              for line_number, line in enumerate(markdown_path.read_text(encoding='utf-8').splitlines(), 1):
+                  if line.lstrip().startswith('```'):
+                      in_fence = not in_fence
+                      fence_count += 1
+                      continue
+                  if in_fence:
+                      continue
+                  for raw_target in link_pattern.findall(line):
+                      target = raw_target.strip().split(' ', 1)[0].strip('<>')
+                      if target.startswith(('http://', 'https://', 'mailto:', '#')):
+                          continue
+                      target = unquote(target.split('#', 1)[0])
+                      if not target:
+                          continue
+                      resolved = (markdown_path.parent / target).resolve()
+                      assert resolved.exists(), f'{markdown_path}:{line_number}: {target}'
+              assert fence_count % 2 == 0, f'unbalanced code fence: {markdown_path}'
+          PY
+
+          git diff --check

AGENTS.md

@@ -0,0 +1,84 @@
+# AGENTS.md — ELUNVERA
+
+## Required reading order
+
+Before changing this repository, read:
+
+1. `README.md`
+2. `docs/PRD.md`
+3. `docs/TRD.md`
+4. `docs/ARCHITECTURE.md`
+5. `docs/DATA_MODEL.md`
+6. `docs/product-technical-gap-baseline.md`
+7. `docs/adr/README.md`
+8. the relevant ADRs and doctoring material
+9. the current pull request, exact head, checks, reviews, and unresolved threads
+
+The repository and current GitHub state are the source of truth. Private memory and prior chat summaries are not.
+
+## Product responsibility
+
+ELUNVERA is the authoritative system for tenant-scoped customer relationship and commercial opportunity facts. It must not absorb capabilities owned by another ContextualWisdomLab product.
+
+Never turn ELUNVERA into:
+
+- an email or calendar host;
+- an ERP, CPQ, accounting, payment, or subscription ledger;
+- an HRIS;
+- a generic issue tracker or project manager;
+- an ontology catalog;
+- an autonomous agent that changes customer or opportunity facts without policy and human authority.
+
+## Data and naming rules
+
+- Database objects use `snake_case` and at least two words.
+- Every tenant-owned row has an enforced tenant boundary.
+- Temporal facts preserve business-valid time and system-recorded time.
+- Relationships are first-class facts with evidence, provenance, confidence, and validity.
+- External IDs are references, never internal primary keys.
+- Provider payloads do not define canonical domain state.
+- Raw PII is not broadcast through events or model traces.
+- Ingestion uses item-level idempotency and records an immutable receipt.
+- Hard delete is forbidden for audit, stage history, relationship history, model evidence, and legal-hold material.
+
+## Engineering rules
+
+- Use Rust for the API, domain services, high-throughput ingestion, security-sensitive logic, graph computations, vector operations, statistics, and model calculations.
+- TypeScript may implement the web interface and generated clients.
+- Python is permitted for non-production validation, research comparison, or connector glue only when no production numerical logic is introduced.
+- Do not suppress deprecation warnings. Fix the cause.
+- Do not introduce arbitrary weights, hard-coded “health scores,” stage-derived probabilities, or rule-of-thumb forecasts.
+- All AI results are proposals or evidence-linked assessments until an authorized workflow accepts them.
+- Do not send customer source content directly to a model provider outside `contextual-orchestrator` contracts.
+- Do not mix unrelated dependency or refactoring changes into a product slice.
+
+## Test and documentation gates
+
+For ELUNVERA-owned production code:
+
+- statement coverage: 100%;
+- branch coverage: 100%;
+- public module/type/trait/function/method documentation: 100%;
+- property and fuzz tests for parser, identifier, temporal, money, and authorization boundaries;
+- real PostgreSQL integration tests;
+- tenant-isolation and purpose-authorization tests;
+- migration clean-install, upgrade, rollback, and restoration rehearsals;
+- CPU/GPU parity and true-parameter recovery for any numerical model;
+- no skipped or ignored required GPU lane;
+- accessibility, keyboard, responsive, print/export, and internationalization tests for user interfaces.
+
+Update `CHANGELOG.md`, `docs/product-technical-gap-baseline.md`, affected ADRs, contracts, and doctoring traceability in the same pull request.
+
+## Pull request operation
+
+Use canonical protected `main` as the ordinary product base. A dependency stack may target its verified prerequisite feature branch while that prerequisite remains open; it must return to `main` once the prerequisite is integrated.
+
+Before commit or push:
+
+1. re-read remote branch and pull-request state;
+2. preserve concurrent agent changes and understand their intent;
+3. remove one-shot or self-modifying workflows after their bounded purpose;
+4. run the exact validation commands claimed in the pull request;
+5. record actual evidence, not anticipated results.
+
+Never claim a check passed if it is queued, pending, skipped, or was run on an older head. Never force-push over another agent’s work merely because the branch changed.