Establish public corporate developer governance and review portal

DEVELOPERS.md

@@ -0,0 +1,148 @@
+# ENTITY Developer Portal
+
+This page is the public engineering gateway for ENTITY, an open-source project stewarded by **Blackmore Technology Group Limited (BTG)**.
+
+ENTITY is designed so that protocol conformance, verification and interoperability can be reproduced outside BTG-controlled infrastructure. BTG stewardship of the public project does not convert BTG hosting, storage, routing or software distribution into sovereign authority over conforming Entity identities or data.
+
+## Start by objective
+
+| Goal | Start here |
+| --- | --- |
+| Understand ENTITY in 10 minutes | [START_HERE.md](START_HERE.md) |
+| Run the reference implementation | [README.md](README.md#quick-start) |
+| Inspect public engineering evidence | [docs/ENGINEERING_EVIDENCE.md](docs/ENGINEERING_EVIDENCE.md) |
+| Understand architecture decisions | [docs/architecture/README.md](docs/architecture/README.md) |
+| Review project governance | [GOVERNANCE.md](GOVERNANCE.md) |
+| Understand release discipline | [docs/governance/RELEASE_POLICY.md](docs/governance/RELEASE_POLICY.md) |
+| Contribute code or documentation | [CONTRIBUTING.md](CONTRIBUTING.md) |
+| Find bounded starter work | [Open contributor tasks](https://github.com/blackmore-technology-group/ENTITY/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) |
+| Attempt independent interoperability | [docs/INTEROPERABILITY_CHALLENGE.md](docs/INTEROPERABILITY_CHALLENGE.md) |
+| Check interoperability status | [docs/interoperability/STATUS.md](docs/interoperability/STATUS.md) |
+| Report a vulnerability | [SECURITY.md](SECURITY.md) |
+| Review the external security-review program | [docs/security/INDEPENDENT_SECURITY_REVIEW_PROGRAM.md](docs/security/INDEPENDENT_SECURITY_REVIEW_PROGRAM.md) |
+| Read technical notes | [docs/papers/README.md](docs/papers/README.md) |
+| See how contributors are recognized | [docs/community/CONTRIBUTOR_RECOGNITION.md](docs/community/CONTRIBUTOR_RECOGNITION.md) |
+| Discuss engineering questions | [GitHub Discussions](https://github.com/blackmore-technology-group/ENTITY/discussions) |
+
+## Current protected release
+
+**ENTITY v3.3.0 — Verifiable Reality, Evidence and Economic Causality**
+
+Protected release commit:
+
+`9c79f987207592cb6791e1a8956f23351cdfb2d3`
+
+Public qualification evidence includes:
+
+- complete regression: **144/144 PASS**;
+- targeted v3.3 suite: **16/16 PASS**;
+- sealed v3.3 reality vectors: **20/20 PASS** — 10 valid / 10 invalid;
+- canonical sealed kit SHA-256: `f8b39ee01fb7346f33a57530e925b545d2bf9a770c7ec60724e28a4971d55a46`;
+- deterministic result SHA-256: `82bd1f1fb328edd37a26d8ea60ede5a599c7d9af5027bffd73b9e52843b5a51d`.
+
+These results are BTG-controlled engineering evidence. They are **not** described as unrelated third-party validation.
+
+## Engineering tracks
+
+### 1. Reproduction and portability
+
+Best for engineers who want to evaluate the project without implementing the protocol.
+
+Typical work:
+
+- reproduce the release on Linux or macOS;
+- validate sealed vectors;
+- identify machine-specific assumptions;
+- benchmark verification;
+- improve onboarding and diagnostics.
+
+### 2. Specification and architecture review
+
+Best for protocol, security, identity, distributed-systems and data-rights engineers.
+
+Typical work:
+
+- identify ambiguous semantics;
+- challenge authority transitions;
+- review canonicalization and signature boundaries;
+- produce counterexamples;
+- review evidence, attestation, recovery and portability semantics.
+
+### 3. Independent implementation
+
+Best for unrelated developers or organizations who want to test whether ENTITY semantics are reproducible from public material alone.
+
+Independent implementations own their own:
+
+- architecture;
+- libraries;
+- code structure;
+- testing strategy;
+- repository;
+- qualification evidence.
+
+BTG-controlled Rust, TypeScript, C#, Go, Swift and Java implementations are reproducibility baselines, **not independent implementations**.
+
+### 4. Live interoperability
+
+This track begins after an independently authored implementation can classify the public vectors correctly.
+
+The target progression is:
+
+`sealed material → independent implementation → vector conformance → reproducible CI → bidirectional live interoperability → sovereign export/recovery survival → independently authored evidence`
+
+Partial results are published as partial results. A failed vector, ambiguity or non-interoperable result is useful evidence and must not be upgraded into a success claim.
+
+### 5. Security research
+
+Security research should focus on concrete boundaries such as:
+
+- cryptographic misuse;
+- signature/canonicalization ambiguity;
+- authority escalation;
+- provider capture;
+- recovery or portability failure;
+- evidence/attestation confusion;
+- external-anchor substitution;
+- rights/usage/settlement authorization flaws.
+
+Use private vulnerability reporting for exploitable findings. Public architectural criticism and non-sensitive counterexamples are welcome in issues or Discussions.
+
+## Public engineering principles
+
+ENTITY development follows several rules that contributors should be able to audit:
+
+1. **Evidence before claims.** Qualification artifacts and exact hashes are published separately from marketing language.
+2. **No silent authority transfer.** Hosting, storage, routing, discovery and custody do not become sovereign authority merely because an infrastructure provider performs them.
+3. **No silent semantic rewrite.** Historical signed state is superseded or migrated explicitly rather than reinterpreted under new rules.
+4. **Independent evidence stays independent.** BTG-controlled testing is never relabeled as third-party validation.
+5. **Protocol versions are reviewable public targets.** Conformance should be possible from public specifications, schemas, vectors and reproducible tooling.
+6. **External-world claims remain contestable.** Cryptographic validity, protocol validity and evidence supporting a claim are separate questions.
+7. **Useful failures are publishable results.** Reproducible failures, counterexamples and ambiguities improve the protocol.
+
+## Contribution lifecycle
+
+A typical contribution moves through:
+
+`issue/discussion → bounded proposal → implementation or evidence → pull request → automated checks → review → merge → release qualification where applicable`
+
+Changes that affect identity, authority, signature meaning, provider independence, recovery, portability, evidence semantics or wire compatibility receive architecture/governance review in addition to ordinary code review.
+
+See [GOVERNANCE.md](GOVERNANCE.md) and [docs/governance/RELEASE_POLICY.md](docs/governance/RELEASE_POLICY.md).
+
+## Corporate stewardship and project independence
+
+Blackmore Technology Group Limited currently stewards ENTITY's specifications, reference implementation, release process and official public repositories.
+
+That stewardship is intentionally separated from protocol sovereignty. A conforming published ENTITY version is not intended to require BTG hosting, BTG DNS, a BTG resolver, a mandatory BTG cloud service or paid permission to use the protocol.
+
+The strongest long-term evidence for that boundary is external reproduction and interoperability by parties BTG does not control.
+
+## Where to participate
+
+- [Issues](https://github.com/blackmore-technology-group/ENTITY/issues) — bounded engineering work, defects, portability findings and specification questions.
+- [Discussions](https://github.com/blackmore-technology-group/ENTITY/discussions) — architecture, design review, implementation questions and broader engineering discussion.
+- [Pull requests](https://github.com/blackmore-technology-group/ENTITY/pulls) — code, documentation and reproducible evidence.
+- [Releases](https://github.com/blackmore-technology-group/ENTITY/releases) — protected public release artifacts and release notes.
+
+If you are evaluating ENTITY for the first time, start with [START_HERE.md](START_HERE.md), then choose one bounded task before attempting a complete implementation.

GOVERNANCE.md

@@ -1,41 +1,215 @@
 # ENTITY Open-Source Governance
 
+## Purpose
+
+This document defines how the public ENTITY project is stewarded, how protocol-impacting decisions are handled, and how Blackmore Technology Group Limited's project stewardship is separated from protocol sovereignty.
+
 ## Stewardship
 
-Blackmore Technology Group Limited stewards the ENTITY specifications, reference implementation, and public release process.
+Blackmore Technology Group Limited (BTG) currently stewards the official ENTITY specifications, reference implementation, release process, project repositories and public engineering evidence.
+
+Stewardship does **not** make BTG the sovereign authority over conforming Entity identities, rights or data merely because BTG publishes software, specifications, resolvers, repositories or infrastructure.
+
+A conforming published protocol version is intended to remain usable without mandatory dependence on BTG-controlled hosting or services.
 
-Stewardship does not make BTG the sovereign authority over conforming Entity identities or data merely because BTG publishes software, specifications, resolvers, or infrastructure.
+## Governance principles
+
+ENTITY governance follows these principles:
+
+1. **Published meaning is stable.** A published protocol version is not silently reinterpreted after release.
+2. **Evidence is separated from claims.** BTG-controlled testing is not relabeled as unrelated external validation.
+3. **Infrastructure is not sovereignty.** Hosting, routing, custody, storage, discovery and software distribution do not automatically create authority.
+4. **Historical signed state is preserved.** New rules supersede or migrate old state explicitly rather than rewriting history.
+5. **Security-critical semantics require explicit review.** Identity, authority, signatures, recovery, portability, evidence, rights and compatibility changes cannot be treated as ordinary refactors when their meaning changes.
+6. **External criticism is useful evidence.** Reproducible failures, ambiguities and counterexamples are valid engineering outcomes.
+7. **Protocol conformance should be publicly reproducible.** Public specifications, schemas, vectors and verification material should be sufficient for an unrelated implementer to test the stated target.
 
 ## Published protocol versions
 
-A published protocol version is immutable in meaning. Corrections are handled through documented errata or a new version.
+A published protocol version is immutable in meaning. Corrections are handled through one or more of:
 
-A conforming implementation of a published version must not require:
+- implementation fixes that preserve semantics;
+- documented errata;
+- clarifying non-normative guidance;
+- an explicitly versioned protocol change.
+
+A conforming implementation of a published version must not require, as a hidden condition of core conformance:
 
 - BTG hosting;
 - BTG DNS;
 - a BTG resolver;
 - a mandatory BTG cloud service;
-- a paid BTG subscription
+- a paid BTG subscription or licence to use the published protocol.
+
+Optional BTG-operated services may exist, but service use must remain distinguishable from core protocol authority and conformance.
 
-unless that dependency is explicitly outside core conformance and chosen by the Entity.
+## Protocol 1.0 freeze
 
-## Conformance
+ENTITY Protocol 1.0 remains **FROZEN_FOR_EXTERNAL_CONFORMANCE** under its separately published freeze and conformance materials.
 
-Conformance is determined by public specifications, schemas, test vectors, and reproducible verification—not by access to private BTG infrastructure.
+That historical target is not rewritten to match later ENTITY releases. Later versions may extend the system while preserving Protocol 1.0 evidence as a distinct historical conformance target.
 
-ENTITY Protocol 1.0 is currently **FROZEN_FOR_EXTERNAL_CONFORMANCE**. Independent external interoperability qualification is still pending.
+Independent external interoperability qualification for that target remains separate from BTG-controlled testing.
 
 ## Decision classes
 
-Implementation-only fixes may be accepted without a protocol revision when they preserve published semantics.
+### Class A — implementation-preserving
+
+Examples:
+
+- bug fixes that preserve published semantics;
+- performance improvements;
+- diagnostics;
+- developer tooling;
+- documentation corrections that do not change normative meaning.
+
+These changes can normally proceed through standard pull-request review and release qualification.
+
+### Class B — architecture-sensitive
+
+Examples:
+
+- changes to internal boundaries that affect security or portability assumptions;
+- new provider/custody integration surfaces;
+- new evidence or rights-processing components;
+- changes that introduce a new durable architectural dependency.
+
+These changes should receive explicit architecture review and may require an ADR.
+
+### Class C — protocol/security semantic
+
+Changes affecting any of the following require explicit governance review and may require a new protocol/version boundary:
+
+- identity-root semantics;
+- authority, delegation or revocation;
+- signature or canonicalization meaning;
+- provider independence;
+- recovery, migration or portability;
+- evidence/attestation state semantics;
+- external reality anchors;
+- historical signed-state interpretation;
+- rights, entitlement, usage or settlement authorization;
+- wire compatibility or conformance behavior.
+
+See [ADR Process](docs/architecture/ADR_PROCESS.md).
+
+## Architecture Decision Records
+
+Durable architecture decisions are recorded under `docs/architecture/`.
+
+ADRs should be used when the project needs a stable public record of:
+
+- context;
+- decision;
+- alternatives;
+- security/sovereignty implications;
+- compatibility effects;
+- consequences;
+- supersession history.
+
+An ADR cannot silently override a frozen protocol target. Protocol semantics must change through the applicable version/governance mechanism.
+
+## Release governance
+
+ENTITY releases are **evidence-gated**, not calendar-promised.
+
+Release readiness should be supported by the qualification appropriate to that release, including regression, targeted tests, manifests/hashes, compatibility review, security-sensitive review and protected-branch checks.
+
+The project maintains a separate [Release Policy](docs/governance/RELEASE_POLICY.md) describing patch/minor/major expectations, evidence gates, historical-integrity rules and claim discipline.
+
+## Conformance governance
+
+Conformance is determined by public specifications, schemas, test vectors and reproducible verification—not by privileged access to private BTG infrastructure.
+
+BTG-controlled cross-language implementations are controlled reproducibility evidence. They are not described as unrelated independent implementations.
 
-Changes affecting identity, authority, signature meaning, portability, recovery, provider independence, evidence semantics, or wire compatibility require documented architecture/governance review.
+External conformance evidence should identify:
+
+- implementation repository/commit;
+- authoring party and relationship to BTG;
+- exact target/version;
+- test command;
+- public result/evidence;
+- known failures or exclusions;
+- whether live interoperability/recovery was attempted.
+
+Current status is published in [Interoperability Status](docs/interoperability/STATUS.md).
+
+## Security governance
+
+Potentially exploitable vulnerabilities use the private reporting process in [SECURITY.md](SECURITY.md).
+
+Security-critical changes must preserve or explicitly version changes to the project's core invariants. A security fix is not permitted to silently trade away provider independence, portability, historical integrity or scoped authority merely to close a defect.
+
+The public external-review pathway is described in [Independent Security Review Program](docs/security/INDEPENDENT_SECURITY_REVIEW_PROGRAM.md).
+
+## Contributor governance
+
+Contributors retain credit for their actual work through Git/GitHub history and project recognition surfaces where appropriate.
+
+Contribution does not automatically imply:
+
+- employment;
+- maintainer authority;
+- endorsement of ENTITY or BTG;
+- independent validation of areas not tested;
+- legal, regulatory or certification opinion.
+
+See [Contributor Recognition](docs/community/CONTRIBUTOR_RECOGNITION.md).
+
+## Maintainers
+
+BTG currently retains stewardship/merge/release authority for the official ENTITY repositories.
+
+If formal external maintainer roles are established later, the project should document each role's:
+
+- scope;
+- review authority;
+- merge authority;
+- release authority;
+- security responsibilities;
+- conflict-of-interest expectations;
+- removal/succession process.
+
+Contributor activity alone does not silently create maintainer authority.
 
 ## Extensions
 
-Vendor- or application-specific extensions must be namespaced and must not silently redefine core ENTITY records.
+Vendor-, deployment- or application-specific extensions must be namespaced and must not silently redefine core ENTITY records or claim conformance by changing the meaning of a published core field.
+
+An extension may add optional behavior without converting its vendor-specific dependency into a core protocol requirement.
 
 ## Historical integrity
 
-Signed historical records are never silently reinterpreted under newer policy or protocol semantics.
+Signed historical records, sealed conformance targets and published release evidence are not silently reinterpreted under newer policy or protocol semantics.
+
+When presentation or documentation later improves, the project prefers:
+
+- new explanatory material;
+- explicit errata where permitted;
+- a new release/version where the target genuinely changes;
+
+rather than weakening verification or rewriting signed historical evidence for cosmetic reasons.
+
+## Technical publications
+
+Informative technical papers are published under [docs/papers](docs/papers/README.md). They explain architecture and threat boundaries but are not automatically normative.
+
+Normative authority remains with the applicable protocol, schemas, freeze/governance documents, release manifests and controlling requirements.
+
+## Public participation
+
+Engineering participation occurs through:
+
+- GitHub Issues for bounded work, defects and specification questions;
+- GitHub Discussions for design/architecture discussion;
+- Pull Requests for reviewable code/documentation/evidence;
+- private security reporting for exploitable vulnerabilities.
+
+The public developer gateway is [DEVELOPERS.md](DEVELOPERS.md).
+
+## Governance changes
+
+Changes to this governance document should themselves be reviewable through the protected pull-request process.
+
+A governance edit cannot retroactively transform BTG-controlled evidence into independent validation or silently change the meaning of a previously frozen/released protocol target.