generated from coulomb/repo-seed
chore(consistency): sync task status from DB [auto]
Updated by fix-consistency on 2026-05-15: - FLEX-WP-0005-T002: todo → in_progress
This commit is contained in:
209
workplans/FLEX-WP-0005-foundations-and-topaz-alignment.md
Normal file
209
workplans/FLEX-WP-0005-foundations-and-topaz-alignment.md
Normal file
@@ -0,0 +1,209 @@
|
||||
---
|
||||
id: FLEX-WP-0005
|
||||
type: workplan
|
||||
title: "Foundations and Topaz Alignment"
|
||||
domain: netkingdom
|
||||
status: todo
|
||||
owner: flex-auth
|
||||
topic_slug: flex-auth
|
||||
planning_priority: P0
|
||||
planning_order: 15
|
||||
depends_on_workplans:
|
||||
- FLEX-WP-0001
|
||||
created: "2026-05-15"
|
||||
updated: "2026-05-15"
|
||||
state_hub_workstream_id: "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
|
||||
|
||||
```task
|
||||
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
|
||||
|
||||
```task
|
||||
id: FLEX-WP-0005-T002
|
||||
status: in_progress
|
||||
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 lint test build` succeeds locally on a fresh clone; CI is
|
||||
green; an SBOM is published and ingested via `ingest_sbom_tool` so the
|
||||
repo's `last_sbom_at` becomes non-null.
|
||||
|
||||
## P5.3 - Pin FlexAuthResourceManifest schema
|
||||
|
||||
```task
|
||||
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
|
||||
|
||||
```task
|
||||
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
|
||||
|
||||
```task
|
||||
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
|
||||
|
||||
```task
|
||||
id: FLEX-WP-0005-T006
|
||||
status: todo
|
||||
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).
|
||||
Reference in New Issue
Block a user