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,262 @@
+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
+
+          relationship_request = openapi.fetch('components').fetch('schemas').fetch('RecordRelationshipRequest')
+          truth_status = relationship_request.fetch('properties').fetch('truth_status')
+          raise 'manual relationship command permits inferred truth' if truth_status.fetch('enum').include?('inferred')
+          evidence_refs = relationship_request.fetch('properties').fetch('evidence_reference_ids')
+          raise 'evidence-backed relationship accepts no evidence' unless evidence_refs['minItems'].to_i >= 1
+          manual_reason = relationship_request.fetch('properties').fetch('manual_assertion_reason')
+          raise 'manual assertion reason must be a string' unless manual_reason['type'] == 'string'
+          raise 'manual assertion reason accepts empty text' unless manual_reason['minLength'].to_i >= 1
+          raise 'manual assertion reason accepts whitespace only' unless manual_reason['pattern'] == '.*\\S.*'
+
+          account_items = openapi.fetch('components').fetch('schemas').fetch('AccountPage').fetch('properties').fetch('items')
+          raise 'AccountPage items must be bounded to page_size maximum' unless account_items['maxItems'] == 100
+
+          ['/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',
+              ),
+              Path('docs/DATA_MODEL.md'): (
+                  'party_record ||--o| person_party : specializes',
+                  'party_record ||--o| organization_party : specializes',
+                  'party_record ||--o| group_party : specializes',
+                  'Exactly one party subtype record must exist and match `party_kind_code`.',
+              ),
+              Path('docs/STORYBOOK_INVENTORY.md'): (
+                  'Japanese',
+                  'Chinese',
+                  'Vietnamese',
+                  'Spanish',
+                  'German',
+                  'French',
+              ),
+              Path('docs/UML.md'): (
+                  'Acknowledged --> Triaged',
+                  'Investigating --> ResponseProposed',
+                  'RemedyInProgress --> VerificationPending',
+                  'Rejected --> Reopened',
+              ),
+              Path('docs/superpowers/plans/2026-08-27-elunvera-foundation-implementation-plan.md'): (
+                  'Consumes: a Keyverse token verifier',
+                  'incorrect issuer, audience, signature, token type, applicable nonce',
+                  '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}'
+
+          plan_text = Path('docs/superpowers/plans/2026-08-27-elunvera-foundation-implementation-plan.md').read_text(encoding='utf-8')
+          assert plan_text.count('cargo +nightly llvm-cov') == 3
+          assert plan_text.count("branches['count'] == branches['covered']") == 3
+          assert 'cargo llvm-cov --workspace --branch' not in plan_text
+          uml_text = Path('docs/UML.md').read_text(encoding='utf-8')
+          assert 'RemedyProposed' not in uml_text
+          assert 'RemedyDelivered' not in uml_text
+          assert 'FollowUp' not in uml_text
+
+          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'
+
+          trailing_whitespace = []
+          for path_text in subprocess.check_output(
+              ['git', 'ls-files'], text=True
+          ).splitlines():
+              payload = Path(path_text).read_bytes()
+              if b'\0' in payload:
+                  continue
+              for line_number, line in enumerate(payload.splitlines(), 1):
+                  if line.endswith((b' ', b'\t')):
+                      trailing_whitespace.append(f'{path_text}:{line_number}')
+          assert not trailing_whitespace, (
+              'tracked text contains trailing whitespace: '
+              + ', '.join(trailing_whitespace)
+          )
+
+          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