flex-auth/workplans/FLEX-WP-0005-foundations-and-topaz-alignment.md

id, type, title, domain, status, owner, topic_slug, planning_priority, planning_order, depends_on_workplans, created, updated, state_hub_workstream_id

id	type	title	domain	status	owner	topic_slug	planning_priority	planning_order	depends_on_workplans	created	updated	state_hub_workstream_id
FLEX-WP-0005	workplan	Foundations and Topaz Alignment	netkingdom	todo	flex-auth	flex-auth	P0	15	FLEX-WP-0001	2026-05-15	2026-05-15	e37d42a9-0018-4a67-a672-ff4e9716b338

FLEX-WP-0005: Foundations and Topaz Alignment

Purpose

Land the decisions, skeleton, and Topaz mapping that the standalone core (FLEX-WP-0002) needs before its first task can be written without leaving load-bearing assumptions implicit.

This workplan is inserted between FLEX-WP-0001 (done) and FLEX-WP-0002 (core) following the pre-implementation assessment captured in docs/pre-implementation-assessment.md.

Sequencing Rationale

• The pre-implementation assessment names a primary threat: the "thin-wrapper-around-Topaz" trap. Aligning vocabulary up front is cheap; aligning it retroactively is not. The Topaz spike therefore moves out of FLEX-WP-0004 and into this workplan.
• The Markitect FlexAuthResourceManifest exists in MKTT-WP-0014 without a flex-auth-side pin. This workplan pins it before 0003 starts importing it.
• Project skeleton, lint, build, and SBOM bring the repo to the same baseline as the other NetKingdom repos so 0002 can land code rather than scaffolding.

P5.1 - Record ADR-001 / ADR-002 / ADR-003

id: FLEX-WP-0005-T001
status: done
priority: high
state_hub_task_id: "8193a278-a044-4397-a4a8-232104374cdc"

Author the three ADRs that close the open decisions identified in the pre-implementation assessment:

• ADR-001 — Implementation language and repo skeleton (Go).
• ADR-002 — Rego-in-Markdown policy package format.
• ADR-003 — Topaz-aligned MVP.

Each ADR is recorded as a decision_type=made event in the State Hub and linked back from this workplan task.

Exit: the three ADRs exist in docs/adr/, are referenced from pre-implementation-assessment.md, and are mirrored as State Hub decisions.

P5.2 - Land Go project skeleton

id: FLEX-WP-0005-T002
status: done
priority: high
state_hub_task_id: "8ac73c33-6d36-4963-990d-28b0d1d60947"

Establish the repo skeleton described in ADR-001:

• cmd/flex-auth/ with a minimal main.go printing version and exit.
• internal/ package tree (registry/, policy/, decision/, audit/, adapters/) with package docs and no business logic yet.
• pkg/api/ with placeholder type definitions for the canonical envelopes (filled in by FLEX-WP-0002 P2.1).
• Makefile targets: build, test, lint, tidy, sbom, fmt.
• golangci.yml configuration mirroring key-cape's lint baseline where reasonable.
• go.mod with the chosen module path and pinned Go version.
• CI configuration (GitHub Actions or equivalent) running make lint test build.

Exit: make ci (vet + lint + test + build) succeeds locally on a fresh clone; GitHub Actions CI is green. SBOM generation works via make sbom (cyclonedx-gomod), but ingest_sbom_tool requires a non-empty dependency source — that step is deferred to the first task that adds an external dependency (FLEX-WP-0002 P2.3, which pulls in the OPA Rego library), where it lands as part of the dep-introduction checklist.

P5.3 - Pin FlexAuthResourceManifest schema

id: FLEX-WP-0005-T003
status: todo
priority: high
state_hub_task_id: "80285e1e-16ec-4f4e-b491-1e79f200219f"

Pin the resource-manifest shape that Markitect's MKTT-WP-0014 already emits, so FLEX-WP-0003 P3.2 imports a known shape and Markitect knows it is producing the right thing.

Steps:

1. Read the Markitect-side emitter and any contract fixtures in markitect-* repos.
2. Capture the agreed shape as schemas/resource_manifest.schema.json plus an example in examples/markitect/resource_manifest.yaml.
3. Add a Go type in pkg/api/ matching the schema, with golden tests.
4. Cross-link from MKTT-WP-0014 (interface change registered through the State Hub) so Markitect knows the pin is canonical.

Exit: the schema, example, and Go type are in this repo; an interface_change event is registered with the State Hub naming flex-auth as the canonical owner of the manifest shape.

P5.4 - Topaz alignment spike

id: FLEX-WP-0005-T004
status: todo
priority: high
state_hub_task_id: "b8a314c3-e98e-4093-bb11-ab8546b8d79b"

Spike Topaz to validate the alignment commitment in ADR-003. Produce a mapping document showing how flex-auth's resource, subject, group, team, and relationship vocabulary corresponds to Topaz directory objects and relations, plus how flex-auth policy packages (Rego-in-Markdown) correspond to Topaz policy modules.

Output:

• docs/topaz-mapping-spike.md covering directory objects, relations, user/group representation, Rego module shape, decision envelope shape, and adapter wire-protocol candidates.
• A small runnable example (examples/topaz/) deploying Topaz locally via docker-compose and evaluating a fixture package end-to-end.
• A recommendation on whether to embed Topaz's directory schema directly in flex-auth's canonical schemas (P2.1) or restate it, with trade-offs.

Exit: the mapping document is committed, reviewed, and referenced from both FLEX-WP-0002 P2.1 and FLEX-WP-0004 T001.

P5.5 - Cite NetKingdom IAM Profile and pin claim consumption

id: FLEX-WP-0005-T005
status: todo
priority: medium
state_hub_task_id: "b31dab7b-e72c-4abe-b6d5-f5875fd0c25a"

The NetKingdom IAM Profile (~/the-custodian/canon/standards/iam-profile_v0.1.md) defines the identity contract flex-auth consumes. Pin the consumption surface:

1. Update INTENT.md and SCOPE.md to cite the profile as a normative upstream.
2. Document required, optional, and tolerated claims in docs/iam-profile-consumption.md.
3. Add a fixture set under examples/claims/ showing key-cape lightweight-mode and Keycloak heavy-mode claim envelopes that flex-auth must accept without code changes.

Exit: a future Rego rule can rely on a documented, stable input shape for claims.

P5.6 - Confirm ops-warden boundary

id: FLEX-WP-0005-T006
status: done
priority: low
state_hub_task_id: "dcd45a14-20fc-49d0-b869-08cda85fcbc5"

Add a one-paragraph clarification in SCOPE.md stating that ops-warden (SSH cert CA for ops actors) and flex-auth (resource authorization for protected systems) operate on disjoint identity surfaces, and note the plausible-but-not-yet-required bridging case (an agt actor appearing as a flex-auth subject in some future flow).

Exit: SCOPE.md has the clarification; no code changes required.

Exit Criteria

• ADR-001, ADR-002, ADR-003 are committed and recorded in the State Hub.
• The Go skeleton compiles, lints, tests, and publishes an SBOM.
• The FlexAuthResourceManifest schema is pinned and Markitect is notified via a registered interface change.
• The Topaz alignment spike has produced a mapping document and a runnable example, both referenced from FLEX-WP-0002 P2.1.
• The NetKingdom IAM Profile citation is in place and claim-consumption fixtures exist.
• The ops-warden boundary is documented in SCOPE.md.

State Hub Mirror

• This workstream blocks FLEX-WP-0002.
• FLEX-WP-0002 keeps its existing dependency on FLEX-WP-0001, but gains a new dependency on this workstream.
• FLEX-WP-0004 loses its Topaz-evaluation dependency on FLEX-WP-0002 for the spike portion (the adapter still depends on the core).