From 3abb56f2f54a6b777b64a83393beb255a51dd8e5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Ren=C3=A9=20White=20Enciso?= Date: Tue, 24 Feb 2026 04:42:38 -0600 Subject: [PATCH] chore(repo): initialize project's repository structure - Adds src/tests/docs scaffolding - Preserves Stage 1 planning tasks - Adds local AI orchestration folders (.agile, tasks) - Applies GitFlow development base branch --- .gitignore | 2 ++ docs/architecture/package-map.puml | 36 +++++++++++++++++++ docs/architecture/repository-charter.md | 33 +++++++++++++++++ .../governance/compatibility-bridge-policy.md | 14 ++++++++ docs/governance/versioning-policy.md | 22 ++++++++++++ docs/migration/adoption-sequence.md | 17 +++++++++ docs/migration/contract-extraction-map.md | 20 +++++++++++ docs/provisioning/checklist.md | 21 +++++++++++ 8 files changed, 165 insertions(+) create mode 100644 .gitignore create mode 100644 docs/architecture/package-map.puml create mode 100644 docs/architecture/repository-charter.md create mode 100644 docs/governance/compatibility-bridge-policy.md create mode 100644 docs/governance/versioning-policy.md create mode 100644 docs/migration/adoption-sequence.md create mode 100644 docs/migration/contract-extraction-map.md create mode 100644 docs/provisioning/checklist.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..31c7257 --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +.tasks/ +.agile/ diff --git a/docs/architecture/package-map.puml b/docs/architecture/package-map.puml new file mode 100644 index 0000000..4025232 --- /dev/null +++ b/docs/architecture/package-map.puml @@ -0,0 +1,36 @@ +@startuml +skinparam shadowing false +skinparam packageStyle rectangle + +title building-block-identity package map + +package "building-block-identity" { + package "Contracts" { + class IssueIdentityTokenRequest + class IssueIdentityTokenResponse + class EvaluateIdentityPolicyRequest + class EvaluateIdentityPolicyResponse + class IdentityPolicyContextRequest + class IdentityPolicyContextResponse + class RefreshIdentitySessionRequest + class RefreshIdentitySessionResponse + } + + package "Abstractions" { + interface IIdentityCapabilityContract + } +} + +package "blueprint-platform" { + class ContractEnvelope +} + +ContractEnvelope <.. IssueIdentityTokenRequest +ContractEnvelope <.. EvaluateIdentityPolicyRequest +ContractEnvelope <.. IdentityPolicyContextRequest + +note bottom +Contracts-only repository. +No runtime or persistence implementation. +end note +@enduml diff --git a/docs/architecture/repository-charter.md b/docs/architecture/repository-charter.md new file mode 100644 index 0000000..3eff478 --- /dev/null +++ b/docs/architecture/repository-charter.md @@ -0,0 +1,33 @@ +# Building Block Identity Repository Charter + +## Purpose +`building-block-identity` is a contracts-only building block repository for transport-neutral identity capability contracts. + +## Ownership +- Identity schema ownership remains with Thalos. +- Contract governance is approved by Thalos maintainers. +- Consumers may depend on contracts only; no identity behavior is hosted here. + +## Scope +- Token issuance contracts +- Policy evaluation contracts +- Policy context contracts +- Session refresh contracts (if approved by governance review) + +## Out of Scope +- Identity business logic +- Runtime adapters +- Persistence concerns +- BFF or Service orchestration + +## Dependency Boundary +Allowed direction: +- `blueprint-platform` -> `building-block-identity` + +Forbidden: +- References to DAL, Service, or BFF layers +- Any dependency on `legacy/` + +## Consumer Boundary +- Thalos repositories consume these contracts as producer/owner. +- Non-Thalos repositories may consume contracts but must not own identity abstractions. diff --git a/docs/governance/compatibility-bridge-policy.md b/docs/governance/compatibility-bridge-policy.md new file mode 100644 index 0000000..02413e2 --- /dev/null +++ b/docs/governance/compatibility-bridge-policy.md @@ -0,0 +1,14 @@ +# Compatibility Bridge Policy + +## Goal +Prevent breaking consumers while moving identity contracts into building-block-identity. + +## Rules +- Keep backward-compatible contract shape for one migration window. +- Additive changes only until all consumers migrate. +- Breaking changes only in a major version. + +## Validation +- Consumer map reviewed before deprecation. +- Compatibility notes published for every release. +- Removal of deprecated shapes requires owner approval. diff --git a/docs/governance/versioning-policy.md b/docs/governance/versioning-policy.md new file mode 100644 index 0000000..837028d --- /dev/null +++ b/docs/governance/versioning-policy.md @@ -0,0 +1,22 @@ +# Building Block Identity Versioning Policy + +## Policy +- Semantic Versioning (`MAJOR.MINOR.PATCH`) is mandatory. +- Backward-compatible contract additions increment `MINOR`. +- Breaking schema changes increment `MAJOR`. +- Non-functional clarifications increment `PATCH`. + +## Compatibility Guarantees +- Existing required fields are not removed in the same major line. +- Field renames require additive migration period before removal. +- Deprecations must include replacement guidance. + +## Release Governance +- Changes require Thalos owner approval. +- Each release includes a consumer impact note. +- Contract ownership statement must remain explicit in release notes. + +## Migration Rules +- Introduce additive fields first. +- Keep dual-shape support for one compatibility window. +- Remove deprecated fields only in next major release. diff --git a/docs/migration/adoption-sequence.md b/docs/migration/adoption-sequence.md new file mode 100644 index 0000000..2a9f9db --- /dev/null +++ b/docs/migration/adoption-sequence.md @@ -0,0 +1,17 @@ +# Adoption Sequence + +## Wave 1 +- thalos-service adopts capability contract namespaces. +- Keep dual-shape support for compatibility. + +## Wave 2 +- thalos-bff adopts capability contract namespaces. +- Validate edge contract compatibility. + +## Wave 3 +- Non-Thalos consumers adopt contracts-only dependency. +- Confirm no identity behavior ownership transfer. + +## Exit Criteria +- No active consumer depends on deprecated Thalos-local contract namespace. +- Deprecation window complete and documented. diff --git a/docs/migration/contract-extraction-map.md b/docs/migration/contract-extraction-map.md new file mode 100644 index 0000000..a1a120e --- /dev/null +++ b/docs/migration/contract-extraction-map.md @@ -0,0 +1,20 @@ +# Identity Contract Extraction Map + +## Source to Target Mapping + +| Current Source | Target Group | Notes | +|---|---|---| +| thalos-service identity token contracts | Contracts/Tokens | Keep payload shape behavior-compatible | +| thalos-service policy contracts | Contracts/Policies | Preserve policy semantics and required fields | +| thalos-service policy context contracts | Contracts/Context | Keep field naming stable for compatibility window | +| thalos-bff refresh session contracts | Contracts/Sessions | Candidate for shared capability standardization | + +## Namespace Strategy +- Current Thalos namespaces are mapped to `BuildingBlock.Identity.Contracts.*`. +- Existing Thalos namespaces remain supported during compatibility window. + +## Extraction Sequence +1. Introduce target contract namespaces in building-block-identity. +2. Add compatibility bridge in Thalos consumers. +3. Migrate service consumers first, then BFF consumers. +4. Deprecate old namespace usage after compatibility window. diff --git a/docs/provisioning/checklist.md b/docs/provisioning/checklist.md new file mode 100644 index 0000000..ca44594 --- /dev/null +++ b/docs/provisioning/checklist.md @@ -0,0 +1,21 @@ +# Stage 7 Provisioning Checklist - building-block-identity + +## Preconditions +- [ ] Ownership rule validated: identity abstractions remain Thalos-owned. +- [ ] Dependency graph validated against `rules/15-workspace-dependency-graph.md`. +- [ ] Repository charter approved. + +## Provisioning Scope +- [ ] Initialize `building-block-identity` repository structure. +- [ ] Create contracts and abstractions modules only. +- [ ] Add docs baseline (`architecture`, `governance`, `consumption`). + +## Guardrails +- [ ] No runtime wiring. +- [ ] No infrastructure adapters. +- [ ] No DAL/Service/BFF dependencies. + +## Handoff +- [ ] Publish package boundary and namespace map. +- [ ] Publish versioning and compatibility policy. +- [ ] Confirm downstream consumers and adoption sequence.