docs: align public technical reference to v4.0.0

.github/SECURITY.md

@@ -1,53 +1,37 @@
 # Security Policy
 
-## Scope
+> **Version 4.0.0 candidate · Unreleased · Last verified 2026-09-01**
 
-This repository contains public documentation only. No production source code,
-credentials, model weights, or client data are stored here. However, we take
-seriously any security-relevant finding that touches Disuza Quantitative's
-public surfaces:
+## CURRENT — scope
 
-- This repository and its contents.
-- The Disuza Quantitative website at [disuza.com](https://disuza.com).
-- Any Disuza-operated endpoints that are reachable from the public internet.
+This repository contains public documentation and its read-only quality
+checks. It does not contain the private trading code, credentials, model
+weights, private datasets, account details, or operational infrastructure.
 
-## Reporting a vulnerability
+Security reports in scope for this policy concern files, workflows, links, or
+metadata published by this repository.
 
-**Please do not open a public GitHub issue for security findings.**
+## CURRENT — reporting
 
-Send an email to **[contact@disuza.com](mailto:contact@disuza.com)** with:
+Do not publish a suspected vulnerability or sensitive value in a GitHub issue.
+Send a minimal report to
+[contact@disuza.com](mailto:contact@disuza.com), including:
 
-- A description of the finding and its suspected impact.
-- Steps to reproduce (proof-of-concept, logs, or scripts as needed).
-- Any suggested mitigation or fix.
-- Your contact details and whether you wish to be credited in an acknowledgment.
+- the affected public file or workflow;
+- the observed impact;
+- safe reproduction steps; and
+- contact details if a reply is requested.
 
-You can also reference the canonical security contact at
-[disuza.com/.well-known/security.txt](https://disuza.com/.well-known/security.txt)
-(RFC 9116).
+Do not include credentials, private data, or unnecessary exploit material.
+Receipt of a report does not create a service-level, bounty, employment, or
+commercial commitment.
 
-## Timelines
+## CURRENT — boundaries
 
-- **Acknowledgment:** within 48 hours of receipt.
-- **Triage and initial response:** within 7 days.
-- **Resolution:** proportionate to severity, typically 30 days or less for
-  confirmed issues on our public surfaces.
-
-## Out of scope
-
-- Third-party services, dependencies, and cloud providers (please report to
-  their respective security teams).
-- Social engineering, physical security, or issues targeting Disuza personnel.
-- Self-inflicted misconfigurations in forks or adaptations of this
-  documentation.
-- Findings already reported or publicly known at the time of your report.
-
-## Recognition
-
-We appreciate coordinated disclosure and will acknowledge researchers who
-report valid findings in good faith (with their permission). Disuza does not
-currently operate a monetary bug-bounty programme.
+This policy does not represent a live trading platform, a public security
+programme for private infrastructure, or a monetary bug bounty. Third-party
+services and dependencies remain governed by their own reporting processes.
 
 ---
 
-*Disuza Quantitative Security — [contact@disuza.com](mailto:contact@disuza.com)*
+Disuza Quantitative Public Technical Reference · v4.0.0 candidate · Unreleased · Last verified 2026-09-01

.github/profile/README.md

@@ -1,79 +1,69 @@
 <div align="center">
 
+<!--
+  Canonical profile copy for this release. GitHub renders an organization
+  profile only from profile/README.md in the organization's public .github
+  repository; synchronize this file there through a separate reviewed PR.
+-->
+
 # Disuza Quantitative
 
-**Private quantitative trading research laboratory · Madrid, Spain · Founded 2025**
+Private pre-deployment quantitative R&D initiative
 
-[Website](https://disuza.com) · [Guest Portal](https://disuza.com/guest) · [Wikidata](https://www.wikidata.org/wiki/Q139491356) · [LinkedIn](https://www.linkedin.com/company/disuza-quantitative/) · [LLM Context](https://disuza.com/llms.txt)
+Public documentation v4.0.0 candidate · Unreleased · Last verified 2026-09-01
 
----
+[Website](https://disuza.com) ·
+[LinkedIn](https://www.linkedin.com/company/disuza-quantitative/) ·
+[Public technical reference](https://github.com/DisuzaQuantitative/Disuza-Quantitative)
 
 </div>
 
-## About
-
-Disuza Quantitative engineers systematic execution algorithms for digital asset
-perpetual futures (BTC, ETH) and US equity index futures (NQ, ES). The firm
-operates proprietary capital and invitation-only partner accounts under a
-closed-access, non-custodial model. It is not a high-frequency
-trading firm, not a retail-facing signal-selling service, and not a public hedge
-fund.
-
-## Founders
+---
 
-- **Yasmine Bendhiab** — Co-Founder & CEO. Strategic operations and corporate
-  compliance. Based in Madrid, Spain.
-  [LinkedIn](https://www.linkedin.com/in/yasmine-bendhiab-22379319a/).
+## CURRENT — about
 
-- **Fares Bendhiab** — Co-Founder & CTO. Lead architect of the quantitative
-  infrastructure. Based in Bizerte, Tunisia.
-  [LinkedIn](https://linkedin.com/in/fares-bendhiab-40866828a) ·
-  [GitHub](https://github.com/FaresDisusa).
+Disuza Quantitative is a private, pre-deployment quantitative R&D initiative
+building and validating rule-based systematic trading infrastructure. Its work
+concerns research governance, validation discipline, software design, and the
+controlled development of a systematic research stack.
 
-## Technology
+The initiative is pre-deployment. Public descriptions must not be read as
+claims of live trading, managed capital, investment services, investment
+performance, legal registration, licensing, regulatory approval, or
+authorization.
 
-Rule-based systematic engine with a layered risk overlay, running on Google
-Cloud. Machine learning is restricted to auxiliary roles (meta-labeling, dynamic
-position sizing, regime detection) per López de Prado's framing — never as the
-primary signal generator. Multi-source ingestion pipeline combining
-exchange market data (OHLCV + L2 + trades + funding + open interest +
-liquidations), redundant venue-direct WebSocket capture for forward-stream
-resilience, macro context, and on-chain regime gating signals used
-strictly as L1-L2 macro context, processed through point-in-time feature
-pipelines. Execution via
-prop-trading-programme APIs and self-custody perpetual venues under
-trade-only permissions.
+Forward-only market-data capture and monitoring are operational for research
+data collection. They do not place orders, operate accounts, connect capital,
+or constitute a trading runtime. A bounded execution-engine contract is
+qualified on deterministic synthetic fixtures only; it has not processed market
+data and does not qualify performance or deployment.
 
-## Regulatory posture
+## Status
 
-Operating in a pre-licensing phase, monitoring the MiCA (EU) and FINMA (Swiss)
-regulatory landscapes. Non-custodial client relationships. CFTC Rule 4.41
-acknowledged for simulated performance. Not soliciting retail investors and not
-offering regulated investment services at this stage.
+| Label | Public meaning |
+| --- | --- |
+| **CURRENT** | Documentation, governance work, and research tooling under controlled development. |
+| **IN PROGRESS** | Validation, data, execution, risk, and operational controls being developed or evaluated. |
+| **TARGET** | An auditable, deployment-ready research and execution stack, subject to qualification gates. |
 
-## Public repositories
+Target-state documentation does not establish present capability.
 
-This organisation maintains a small number of public repositories for technical
-reference and transparency:
+## Public repository
 
 - **[Disuza-Quantitative](https://github.com/DisuzaQuantitative/Disuza-Quantitative)**
-  — the living technical reference. Architecture, methodology, and operations.
+  — the versioned public technical reference, including machine-readable
+  [public facts](../../PUBLIC_FACTS.yml).
 
-Source code for the trading platform itself is proprietary and not hosted on
-GitHub.
+The repository does not publish a production trading platform, proprietary
+source code, private datasets, model weights, secrets, or a performance record.
 
 ## Contact
 
-**[contact@disuza.com](mailto:contact@disuza.com)** — all inquiries.
+[contact@disuza.com](mailto:contact@disuza.com)
 
----
+## Licence
 
-<div align="center">
-
-*Disuza Quantitative is a closed-access research laboratory. Documentation is
-released under CC BY 4.0; source code, model weights, trademarks, and
-operational know-how remain proprietary.*
-
-**© 2025-2026 Disuza Quantitative**
-
-</div>
+Current public documentation is available under
+[CC BY 4.0](../../LICENSE).
+Historical grants remain governed by the notices shipped with their exact
+versions.

.github/pull_request_template.md

@@ -1,40 +1,46 @@
-<!--
-  This repository does not accept external pull requests.
+## Summary
 
-  If you are outside Disuza Quantitative, please close this PR and open an
-  issue instead. We will address documentation corrections or clarifications
-  in subsequent internal commits.
+<!-- What changed and why. Keep claims evidence-bounded. -->
 
-  If you are inside Disuza Quantitative, thank you — please remove this
-  comment and complete the template below.
--->
+## Public-facts contract
 
-## Summary
+- [ ] I checked every changed claim against `PUBLIC_FACTS.yml`.
+- [ ] Present capabilities are labelled **CURRENT**.
+- [ ] Unfinished and future capabilities are labelled **IN PROGRESS** or
+      **TARGET**.
+- [ ] This change makes no unsupported live, production, performance,
+      investment-service, legal-status, or regulatory-readiness claim.
 
-<!-- What changed and why. One short paragraph. -->
+## Confidentiality
 
-## Consistency with facts.ts
+- [ ] No internal identifiers, results, trial or split details, data locators,
+      hashes, infrastructure coordinates, access details, secrets, thresholds,
+      counterparties, or private-repository identifiers are included.
 
-- [ ] I have verified these docs are consistent with the FACTS_PUBLIC export
-      in the website repo (`lib/facts.ts`).
-- [ ] This PR does not introduce new facts that are not already in the site's
-      published `llms.txt` / `llms-full.txt`.
+## Automated and visual checks
 
-## IP-safety grep
+- [ ] The `Public surface` workflow is green.
+- [ ] Markdown, links, anchors, CFF, Mermaid, and secret scanning pass.
+- [ ] I previewed the GitHub Markdown and the 1200×630 Open Graph image.
 
-- [ ] I ran the IP-safety grep and it returns `✓ IP-safe`.
+## Release boundary
 
-## Rendering check
+- [ ] The maintainer checked biographies and responsibilities against current
+      source material.
+- [ ] The maintainer confirmed `contact@disuza.com` as the public contact.
+- [ ] The maintainer checked CC BY 4.0 and `NOTICE.md` against the intended
+      public licence boundary.
+- [ ] Candidate version and verification markers are current; any release date
+      is added only when the release actually occurs.
 
-- [ ] I previewed this PR on GitHub and confirmed Mermaid diagrams render
-      correctly.
-- [ ] Cross-references (links between doc pages) resolve.
+## Downstream boundary
 
-## Version bump
+- [ ] This PR does not modify `disuza.com`, `/guest`, `llms.txt`,
+      `llms-full.txt`, the organization-level `.github` repository, LinkedIn,
+      Wikidata, or SEO metadata outside this repository.
+- [ ] Follow-up work is tracked in
+      `docs/downstream-alignment-checklist.md`.
 
-If this PR materially changes the documentation surface:
+---
 
-- [ ] I have updated `CHANGELOG.md`.
-- [ ] I have updated the `last_updated` HTML comments on every touched page.
-- [ ] If this is a new version, I have updated the version marker in the
-      root `README.md` and `CITATION.cff`.
+Disuza Quantitative Public Technical Reference · contribution checklist

.github/workflows/docs-quality.yml

@@ -0,0 +1,104 @@
+name: Public documentation quality
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: docs-quality-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  public-surface:
+    name: Public surface
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 1
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Validate public facts, claims, links, and anchors
+        run: python scripts/check_public_surface.py
+
+      - name: Install strict YAML validator dependency
+        run: python -m pip install --disable-pip-version-check --no-input PyYAML==6.0.2
+
+      - name: Validate YAML syntax and reject duplicate keys
+        run: python scripts/validate_yaml.py
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: "22"
+
+      - name: Lint Markdown
+        run: npx --yes markdownlint-cli2@0.22.1
+
+      - name: Check external links
+        uses: lycheeverse/lychee-action@v2
+        with:
+          args: >-
+            --config .lychee.toml
+            './README.md'
+            './CONTRIBUTING.md'
+            './CHANGELOG.md'
+            './NOTICE.md'
+            './**/*.md'
+            './.github/**/*.md'
+            './CITATION.cff'
+            './PUBLIC_FACTS.yml'
+            './LICENSE'
+          fail: true
+          jobSummary: false
+          lycheeVersion: "v0.23.0"
+          output: /tmp/lychee.md
+
+      - name: Validate citation metadata
+        uses: citation-file-format/cffconvert-github-action@2.0.0
+        with:
+          args: "--validate"
+
+      - name: Render canonical Mermaid diagram
+        run: |
+          python scripts/extract_mermaid.py \
+            docs/architecture.md \
+            /tmp/target-architecture.mmd
+          npx --yes @mermaid-js/mermaid-cli@11.15.0 \
+            --input /tmp/target-architecture.mmd \
+            --output /tmp/target-architecture.svg \
+            --puppeteerConfigFile scripts/mermaid-puppeteer-config.json \
+            --quiet
+
+      - name: Install Gitleaks
+        env:
+          GITLEAKS_VERSION: "8.30.1"
+          GITLEAKS_ARCHIVE_SHA256: "551f6fc83ea457d62a0d98237cbad105af8d557003051f41f3e7ca7b3f2470eb"
+        run: |
+          curl --fail --silent --show-error --location \
+            "https://github.com/gitleaks/gitleaks/releases/download/v${GITLEAKS_VERSION}/gitleaks_${GITLEAKS_VERSION}_linux_x64.tar.gz" \
+            --output /tmp/gitleaks.tar.gz
+          echo "${GITLEAKS_ARCHIVE_SHA256}  /tmp/gitleaks.tar.gz" | sha256sum --check
+          tar --extract --gzip --file /tmp/gitleaks.tar.gz --directory /tmp gitleaks
+
+      - name: Scan current tree for secrets with redacted output
+        run: >-
+          /tmp/gitleaks dir
+          --redact=100
+          --no-banner
+          --no-color
+          .

.lychee.toml

@@ -0,0 +1,10 @@
+accept = [200, 204, 206, 429]
+include_mail = false
+max_retries = 3
+retry_wait_time = 2
+timeout = 20
+
+# These services block automated link checkers even when the public page exists.
+exclude = [
+  "^https://(?:www\\.)?linkedin\\.com/",
+]