BLACKSWAN Implementation Standards

Version: v0.1 — DRAFT (authored 2026-07-11) Sponsor: Mamadou Ly, Founder, Managing Partner & CEO Scope: This document codifies the coding, repository, CI/CD, testing, security, deployment, documentation, and AI-agent disciplines the BLACKSWAN estate already exercises. It is a DRAFT, not a SKELETON: most of it is a curation of patterns shipped across the CMOS EOC rhythm, HSOS CC-era waves, and PMOS/AIOS Sprint work. Every rule in §2–§9 either cites a shipped precedent in §11 or is explicitly marked (Prospective — first application TBD). Read time: ~9 minutes.

0. Preface

Status: v0.1 · DRAFT. This is a DRAFT, not a SKELETON and not a freeze. Where BSRA v0.1 is honestly a SKELETON — a reference architecture whose substance is still deferred to future Waves — Implementation Standards can be substantively populated now, because the estate has already exercised most of these disciplines in shipped work. The job of v0.1 is curation and codification, not net-new specification.

Authored: 2026-07-11.

Sponsor: Mamadou Ly, Founder, Managing Partner & CEO.

Position in the governance stack

BLACKSWAN Estate Canon v2.2              ← constitutional governance
    ↓ referenced by
BLACKSWAN Reference Architecture v0.1     ← BSRA (technical reference architecture · SKELETON)
    ↓ referenced by
BLACKSWAN Gateway Experience Standard     ← BGXS v0.2 DRAFT (public gateway experience)
    ↓ consumes tokens from
BLACKSWAN Enterprise Design Language      ← BEDL v0.1 DRAFT (visual + interaction system)
    ↓ realised through
BLACKSWAN Implementation Standards v0.1   ← THIS DOCUMENT (coding · repos · CI · testing · security · deploy)

Implementation Standards sits at the bottom of the governance stack: it is where the constitutional statements of the Canon, the architecture of BSRA, the experience of BGXS, and the tokens of BEDL are realised as shipped code. Where this document and any layer above it speak to the same subject, the higher layer wins. This document never amends the Canon, BSRA, BGXS, or BEDL — it references them.

Nature: curation, not net-new specification

Every discipline below is traceable to a pattern the estate has already exercised:

CMOS EOC rhythm — the Entra OIDC 5-ticket rhythm (EOC-00 through EOC-04) established the commit identity, scope-doc, verifier-tail, redirect-allowlist, and judgment-call disciplines.
HSOS CC-era waves — established the .chain/ seal-add-only rule.
PMOS Sprint work — established the ticket-prefixed branch and wave-drilldown patterns.
AIOS row-registry work — established fixture-as-contract discipline against the row schema.

If a rule cannot be traced to at least one shipped precedent, it carries a (Prospective — first application TBD) marker inline and appears under the prospective sub-list in §11. Nothing here is invented that the estate has not exercised.

Versioning

Implementation Standards inherits the Canon §0 v1.x / vN.x amendment discipline.

v0.x — DRAFT evolution. Sections mature and prospective rules graduate to cited as the estate exercises them; the version bumps as rules mature.
v1.0 — first substantive freeze, reached only when every rule in §2–§9 cites a shipped precedent (no prospective markers remain) and the document has passed one external-review cycle.

1. Reader's guide

This document is for engineers and coding agents — human or AI — shipping code across BLACKSWAN planes. If you are about to open a branch, write a commit, add a test, wire a CI gate, or land a security control, this is the document that tells you the shape the estate already expects.

Every rule here is one of two kinds: (a) a discipline the estate has already exercised and now codifies — these cite a shipped PR or scope doc in §11 — or (b) a discipline the estate intends but has not yet exercised — these are explicitly marked (Prospective — first application TBD) and listed under the prospective sub-list in §11. Read the citation to know whether a rule is battle-tested or aspirational.

If you are looking for constitutional governance, read the Canon. For technical architecture, read BSRA. For the public gateway experience, read BGXS. For visual and interaction tokens, read BEDL. For per-plane ESLint / Prettier configs and CI workflow YAML, read the plane repo — this document references those artifacts but does not author them (see §10).

2. Coding standards

2.1 Languages (canonical per Canon §4)

TypeScript for new frontend and Node backend surfaces.
Python for AI / analytics surfaces.
SQL (PostgreSQL dialect per Canon §4).
No Go, no Rust, no Java, no C# at v0.1 unless a plane's charter explicitly requires one.

Precedent: §11 — Canon §4 canonical stack; TypeScript exercised across all five CMOS EOC PRs.

2.2 Style

TypeScript: strict mode; no any in production code (test fixtures may use any sparingly).
ESLint + Prettier, enforcement via CI (config lives per plane — see §10).
2-space indent (project convention already exercised across CMOS).
File names kebab-case.ts; component names PascalCase.tsx; test files *.test.ts.

Precedent: §11 — CMOS EOC repo style, exercised EOC-00 through EOC-04.

2.3 Comments

Every non-trivial function carries a JSDoc / TSDoc block.
The sponsor line NEVER appears in code files — only in docs and PRs (per Canon §5 and §8.3 below).
No forbidden phrases (Canon §9) in comments outside chain-only scope.

EOC-style audit comments are the canonical inline-provenance pattern:

// EOC-04 SHIPPED: landingActivation retained; no prior assertion block mutated

Precedent: §11 — CMOS EOC-04 inline audit-comment convention.

2.4 Error handling

Every async boundary handles rejection — no unhandled promise rejections cross a module edge.
No swallowed exceptions.
User-facing errors go through a single error-shape (a typed union) per plane.

Precedent: §11 — CMOS EOC Access-stage error handling (typed error union across the OIDC callback boundary).

3. Repository conventions

§3 recalls Canon §5 and codifies additional operational rules the estate already exercises.

3.1 Branch names

Ticket-prefixed kebab-case: eoc-04-falcon-landing-flip, pb-111-wave-3-drilldown.
No slashes; ASCII hyphen only; lowercase.
Never feature/, bugfix/, or chore/ prefixes — the ticket id is the whole categorisation.

Precedent: §11 — CMOS EOC branch names; PMOS PB-111 wave-drilldown branch.

3.2 Commits

Sponsor identity mandatory:

git -c user.name="Mamadou Ly" -c user.email="yhvk9sj7k7@privaterelay.appleid.com"

Commit message shape: <PLANE> <TICKET> · <one-line summary>, followed by an optional body.
Never “landed” in a commit message — always SHIPPED (Canon §6).

Precedent: §11 — CMOS PR #43 (EOC-00) established the commit identity discipline.

3.3 PR shape

Title mirrors the terminal commit message.
Body must include: files touched, verifier tail, non-goals attestation, sponsor line.
Closes #N keyword when closing a P0 gate or tracked issue.
Squash-merge with --delete-branch only (Canon §5).

Precedent: §11 — CMOS EOC PR bodies, EOC-00 through EOC-04.

3.4 Protected branches

main is protected across every canonical repo.
No direct push; PR required; conversation resolution required; no force push; no branch deletion of main.

Precedent: §11 — Canon §5 branch-and-merge policy, enforced across all canonical repos.

3.5 `.chain/` files

Every seal file is byte-immutable once SHIPPED.
Terminal seals may be ADDED; existing seals are never modified or reordered.
No coding agent may touch .chain/ unless the PR is explicitly a seal-addition PR.

Precedent: §11 — HSOS CC-era wave PRs established the seal-add-only rule; Canon §5 .chain/ seals.

4. CI / CD

4.1 Every plane repo has

A readiness-regression suite that runs on every PR.
A GitHub Actions workflow that runs the suite plus CodeQL for js-ts (Canon §4: GitHub Actions canonical).
A verifier tail asserted as part of the readiness suite.

Precedent: §11 — CMOS EOC Actions workflow, exercised EOC-01 through EOC-04.

4.2 Merge gate

Readiness regression MUST pass.
Actions security scan MUST pass.
CodeQL js-ts MAY be pending at merge time — established as non-blocking across all five CMOS EOC PRs.

Precedent: §11 — CMOS EOC merge-gate posture, EOC-00 through EOC-04.

4.3 Verifier discipline

Every wave / ticket appends its own assertion block and NEVER mutates a prior assertion block. The single documented exception is EOC-04, recorded in the CMOS EOC-04 scope doc.
The verifier tail is a single stdout line naming the wave and its integrity claim.

Format:

<PLANE> <TICKET> <what-was-verified>: OK · <invariants-summary>

Precedent: §11 — CMOS EOC-01 through EOC-04 verifier tails.

5. Testing

5.1 Test frameworks

Node.js: node's built-in assert module (as exercised across CMOS).
Python: pytest.
No Jest, no Mocha, no Chai at v0.1 unless a plane charter explicitly requires one.

Precedent: §11 — CMOS EOC readiness suites built on node assert.

5.2 Fixture discipline

The LCGX fixture-invariant (see wiki concepts/lcgx-fixture-invariant) applies estate-wide as a discipline analogue: fixture counts are contracts, not incidentals.
Every fixture file has a stable id and a documented purpose.
Fixture mutations count as verifier-breaking — add new fixtures, do not mutate existing ones.

Precedent: §11 — concepts/lcgx-fixture-invariant; AIOS row-registry fixture-count contracts.

5.3 Test naming

Describe the invariant being asserted, not the code being called.
Bad: test('calls buildAllowedRedirectHosts')
Good: test('EOC-03: ALLOWED_REDIRECT_HOSTS union preserves Sprint 1 default hosts')

Precedent: §11 — CMOS EOC-03 redirect-allowlist test naming.

5.4 Coverage

No numeric coverage threshold at v0.1 (Prospective — first application TBD); a per-plane threshold will be set once posture lifts.
Every P0 gate MUST have a dedicated assertion block in the plane's verifier.

Precedent: §11 — P0-gate assertion blocks: CMOS EOC verifier. Coverage threshold: prospective.

6. Security

6.1 Secrets

No secrets in code, ever.
No secrets in scope docs, briefs, or PR bodies.
Entra secrets live in the Entra tenant plus the secret store (Azure Key Vault per Canon §4).
Rotation policy per the EOC-01 template.

Precedent: §11 — CMOS EOC-01 secret-handling and rotation template.

6.2 Redirect-URI enforcement

Every plane that participates in the SSO chain MUST enforce the redirect-allowlist union pattern (EOC-03 canonical implementation).
https:// only for production redirect entries (EOC-02 lock).
http://localhost is permitted only in the sibling dev-allowlist array (EOC-03 design).

Precedent: §11 — CMOS EOC-02 (https lock), CMOS EOC-03 (allowlist union + sibling dev array).

6.3 Data classification `(Prospective — first application TBD)`

Ladder: Public · Internal · Restricted · Confidential.
Confidential data may never appear in a scope doc, brief, PR body, or verifier output.
Restricted data may appear in an internal wiki page only.

Precedent: §11 — prospective; no shipped precedent yet.

6.4 Prototype banner

Every deployed surface carries the Canon §6 banner: “Visual prototype — do not submit real confidential, KYC, payment, or institutional data.”
Removal is a canonical prohibition per Canon §9.

Precedent: §11 — Canon §6 posture banner, carried on every deployed prototype surface.

7. Deployment

7.1 Environments

Every plane has: local, preview (PR-scoped), staging, production.
All planes are currently STANDBY · IN-MEMORY ONLY · HOLD · NO-GO per Canon §6 — production deploys are stubbed until posture lifts.

Precedent: §11 — Canon §6 estate posture; CMOS preview environments on EOC PRs.

7.2 Deployment identity

Every deployment run is bound to the sponsor identity plus a deploy-token issued from a service principal.
No coding agent may issue a production deploy without an explicit sponsor-approved deploy PR.

Precedent: §11 — Canon §5 commit identity extended to deploy identity; CMOS preview-deploy binding.

7.3 Rollback

Every deployment has a documented rollback (image tag or migration reversal).
Rollback rehearsals happen at each Wave transition (Prospective — first rehearsal at first production deploy).

Precedent: §11 — rollback documentation: CMOS preview-deploy notes. Rollback rehearsals: prospective.

8. Documentation

8.1 Scope-doc discipline (per CMOS EOC precedent)

Every ticket that mutates a canonical assertion, host, or verifier tail SHIPS a scope doc in docs/p0-gates/ (or the per-plane analogous folder).
Scope docs are historical narrative — once SHIPPED, they are NOT re-edited except for a one-line forward-reference.
Scope docs cite the Canon and BGXS versions consumed.

Precedent: §11 — docs/p0-gates/entra-oidc-*.md across CMOS EOC-00 through EOC-04.

8.2 README

Every canonical repo has a README.md at root.
The README states: plane name, posture, sponsor line, entry-point script, verifier command.
The README uses the lowercase repo name in body text per Canon §5.1.

Precedent: §11 — CMOS repo README; Canon §5.1 lowercase-repo-name convention.

8.3 Sponsor line

Sponsor line verbatim: Mamadou Ly, Founder, Managing Partner & CEO.
Present in every scope-doc footer, every canonical top-level doc footer, and every PR body.
Never appears in source code.

Precedent: §11 — Canon §3 sponsor line (verbatim); carried in every CMOS EOC scope-doc footer.

9. AI coding-agent discipline

9.1 Attribution

Every AI-produced commit carries the sponsor identity (see §3.2). No AI-agent identity appears in commit metadata.
PR bodies produced by an AI subagent SHOULD note the subagent type (Claude Code / Codex) in an internal-only section, not as user-facing copy.

Precedent: §11 — CMOS EOC PRs authored under sponsor identity by coding agents.

9.2 Prohibitions specific to AI agents

An AI agent:

MUST NOT edit .chain/ seal files.
MUST NOT propose Canon amendments inside artifact PRs (Canon §9 item 16).
MUST NOT introduce forbidden phrases (Canon §9) outside chain-only scope.
MUST NOT fabricate hosts, ports, or secrets — either look them up or leave a TBD-<TICKET> marker.

Precedent: §11 — Canon §9 prohibitions; CMOS EOC TBD-<TICKET> marker usage.

9.3 Judgment-call handling

When a brief's rule conflicts with a stronger invariant, the AI agent MAY deviate and MUST report the deviation in the PR body under a “Judgment call worth flagging” section.

Precedent: §11 — CMOS EOC-03 (sibling redirectAllowlistDev array), CMOS EOC-04 (landingActivation retention).

10. What Implementation Standards is NOT

Not a code-style-guide substitute for ESLint / Prettier configs — those live per plane.
Not a compliance framework.
Not a runbook.
Not authoritative on any plane's internal architecture — planes remain sponsor-owned deployment units per Canon §1.
Not a substitute for BEDL — visual tokens are BEDL's remit.
Not a substitute for BSRA — technical architecture is BSRA's remit.

11. Precedents index

Every rule in §2–§9 is either cited (traceable to a shipped PR or scope doc) or prospective (intended, not yet exercised). The two sub-lists below make the split explicit.

11.1 Cited (shipped precedent established the pattern)

Rule	Shipped precedent
§2.1 Languages	Canon §4 canonical stack; TypeScript across all five CMOS EOC PRs
§2.2 Style	CMOS EOC repo style, EOC-00 through EOC-04
§2.3 Comments / EOC audit comments	CMOS EOC-04 inline audit-comment convention
§2.4 Error handling	CMOS EOC Access-stage typed error union
§3.1 Branch names	CMOS EOC branch names; PMOS PB-111 wave-drilldown branch
§3.2 Commit identity	CMOS PR #43 (EOC-00) established the commit identity discipline
§3.3 PR shape	CMOS EOC PR bodies, EOC-00 through EOC-04
§3.4 Protected branches	Canon §5 branch-and-merge policy, all canonical repos
§3.5 `.chain/` immutability	HSOS CC-era wave PRs established the seal-add-only rule
§4.1 CI suite + Actions + CodeQL	CMOS EOC Actions workflow, EOC-01 through EOC-04
§4.2 Merge gate (CodeQL non-blocking)	CMOS EOC merge-gate posture, all five EOC PRs
§4.3 Verifier tail	CMOS EOC-01 through EOC-04 verifier tails
§5.1 Test frameworks (node `assert`, pytest)	CMOS EOC readiness suites on node `assert`
§5.2 Fixture invariant	`concepts/lcgx-fixture-invariant`; AIOS row-registry fixture-count contracts
§5.3 Test naming	CMOS EOC-03 redirect-allowlist test naming
§5.4 P0-gate assertion block	CMOS EOC verifier assertion blocks
§6.1 Secrets / rotation	CMOS EOC-01 secret-handling and rotation template
§6.2 Redirect-URI enforcement	CMOS EOC-02 (https lock), CMOS EOC-03 (allowlist union + sibling dev array)
§6.4 Prototype banner	Canon §6 posture banner on every deployed prototype surface
§7.1 Environments	Canon §6 estate posture; CMOS preview environments on EOC PRs
§7.2 Deployment identity	Canon §5 commit identity extended to deploy identity; CMOS preview-deploy binding
§7.3 Rollback documentation	CMOS preview-deploy rollback notes
§8.1 Scope-doc discipline	`docs/p0-gates/entra-oidc-*.md`, CMOS EOC-00 through EOC-04
§8.2 README	CMOS repo README; Canon §5.1 lowercase-repo-name convention
§8.3 Sponsor line	Canon §3 sponsor line; every CMOS EOC scope-doc footer
§9.1 AI attribution	CMOS EOC PRs authored under sponsor identity by coding agents
§9.2 AI prohibitions	Canon §9 prohibitions; CMOS EOC `TBD-<TICKET>` marker usage
§9.3 Judgment-call handling	CMOS EOC-03 (`redirectAllowlistDev`), CMOS EOC-04 (`landingActivation` retention)

11.2 Prospective (no shipped precedent yet · first application TBD)

Rule	Status
§5.4 Coverage threshold	Prospective — per-plane numeric threshold set once posture lifts
§6.3 Data classification ladder	Prospective — Public · Internal · Restricted · Confidential ladder not yet exercised
§7.3 Rollback rehearsals	Prospective — first rehearsal at first production deploy

12. Sponsor line

BLACKSWAN Implementation Standards · v0.1 — DRAFT · authored 2026-07-11 · sponsor Mamadou Ly, Founder, Managing Partner & CEO.