pdurlej/platform

Fork 0

feat(modules/traefik): upgrade manifest to v2 cataloging #103

New issue

Closed

opened 2026-05-06 00:26:06 +02:00 by claude · 2 comments

claude commented

2026-05-06 00:26:06 +02:00

Collaborator

Decomposed from meta-issue #70 — Phase 02 v2 cataloging pilot. Priority rank: 7/8.

Spec sources (whitelist)

modules/traefik/module.yaml — current v1 manifest
modules/traefik/runbook.md — operator runbook (if exists)
schema/module.schema.v2.json — v2 fields spec
schema/module.schema.json — v1 baseline
Live runtime via SSH: docker inspect <container-from-runbook> on appropriate host (RS 2000 unless module is VPS-1000)
AGENTS.md §"Current phase" — v2 audit fields list

Extracted context

From schema/module.schema.v2.json description:

Additive extension to v1. Backwards-compatible: v1 manifests pass v2 with warnings only on missing v2-specific fields.
v2 fields: predecessor, alternatives, todo_cap, drift_audit.

From AGENTS.md §"Current phase":

spec.intent.purpose, spec.intent.user_facing_outcome, spec.intent.acceptance_criteria,
spec.runtime.image_observed (full digest, no truncation),
spec.runtime.statefulness, optional spec.risk.acknowledged_risks

Why this exists (product-first)

Traefik is the platform's edge (every *.pdurlej.com route goes through it). v2 cataloging ensures the edge module is at canonical schema. Plus exposure classification verification (per #74 contract): traefik labels are the source of truth for which routes are public/tailnet/auth.

Allowed touched paths

modules/traefik/module.yaml (modify) — ONLY

Do NOT touch other manifests, schema files, runbook (separate atomic if runbook needs update), or any code.

What "done" looks like

spec.intent.purpose written (1 line)
spec.intent.user_facing_outcome written (≤4 sentences; user/owner-facing language, not tech)
spec.intent.acceptance_criteria written (≥2 verifiable bullets)
spec.runtime.image_observed matches live docker inspect <container> RepoDigests output (FULL sha256:... digest, no truncation)
spec.runtime.image_audit_ts set to RFC3339 UTC of when verified
spec.runtime.image_build set to 'registry' or 'local'
spec.runtime.statefulness set to 'stateless'
spec.runtime.acknowledged_risks documents edge SPOF + acme.json sacred-path note
module.yaml validates against module.schema.v2.json (manual: python3 -m jsonschema -i modules/traefik/module.yaml schema/module.schema.v2.json; auto via platformctl validate once #63 lands)

Suggested approach

Read current modules/traefik/module.yaml to know baseline
SSH to host, run docker inspect for the running container, capture RepoDigest
Read runbook (if exists) for user-facing context
Fill v2 fields per "What done looks like" checklist
Validate locally via jsonschema before opening PR
Run tests/smoke.sh traefik — should still pass (this PR shouldn't change runtime behavior)

Escape hatch

If image_observed from runtime differs from current manifest: STOP, comment on this issue with the discrepancy. Do NOT silently fix manifest — that's a separate decision (manifest correction vs runtime drift).
If runbook claims behavior the module doesn't actually do: STOP, comment.
If module is on a different host than runbook claims: STOP, comment.

Risk class

risk/process — incorrect v2 manifest blocks platformctl validate; downstream blocks Phase 03

Dependencies

Depends on Issue #63 (platformctl validate jsonschema) — until #63 lands, agent uses python3 -m jsonschema directly
Depends on Issue #66 (L4-Verify suite) — once #66 lands, this PR auto-validated end-to-end

Trace

Parent meta-issue: #70
Priority rank: 7/8 per #70 heuristic
Decomposed by: claude (orchestrator), 2026-05-06
Per agent-execution-template.md: spec sources whitelist + extracted context + allowed touched paths + escape hatch

**Decomposed from meta-issue #70 — Phase 02 v2 cataloging pilot. Priority rank: 7/8.** ## Spec sources (whitelist) - `modules/traefik/module.yaml` — current v1 manifest - `modules/traefik/runbook.md` — operator runbook (if exists) - `schema/module.schema.v2.json` — v2 fields spec - `schema/module.schema.json` — v1 baseline - Live runtime via SSH: `docker inspect <container-from-runbook>` on appropriate host (RS 2000 unless module is VPS-1000) - `AGENTS.md` §"Current phase" — v2 audit fields list ## Extracted context > From `schema/module.schema.v2.json` description: > ``` > Additive extension to v1. Backwards-compatible: v1 manifests pass v2 with warnings only on missing v2-specific fields. > v2 fields: predecessor, alternatives, todo_cap, drift_audit. > ``` > From `AGENTS.md` §"Current phase": > ``` > spec.intent.purpose, spec.intent.user_facing_outcome, spec.intent.acceptance_criteria, > spec.runtime.image_observed (full digest, no truncation), > spec.runtime.statefulness, optional spec.risk.acknowledged_risks > ``` ## Why this exists (product-first) Traefik is the platform's edge (every `*.pdurlej.com` route goes through it). v2 cataloging ensures the edge module is at canonical schema. Plus exposure classification verification (per #74 contract): traefik labels are the source of truth for which routes are public/tailnet/auth. ## Allowed touched paths - `modules/traefik/module.yaml` (modify) — ONLY Do NOT touch other manifests, schema files, runbook (separate atomic if runbook needs update), or any code. ## What "done" looks like - [ ] `spec.intent.purpose` written (1 line) - [ ] `spec.intent.user_facing_outcome` written (≤4 sentences; user/owner-facing language, not tech) - [ ] `spec.intent.acceptance_criteria` written (≥2 verifiable bullets) - [ ] `spec.runtime.image_observed` matches live `docker inspect <container>` RepoDigests output (FULL `sha256:...` digest, no truncation) - [ ] `spec.runtime.image_audit_ts` set to RFC3339 UTC of when verified - [ ] `spec.runtime.image_build` set to 'registry' or 'local' - [ ] `spec.runtime.statefulness` set to 'stateless' - [ ] `spec.runtime.acknowledged_risks` documents edge SPOF + acme.json sacred-path note - [ ] `module.yaml` validates against `module.schema.v2.json` (manual: `python3 -m jsonschema -i modules/traefik/module.yaml schema/module.schema.v2.json`; auto via `platformctl validate` once #63 lands) ## Suggested approach 1. Read current `modules/traefik/module.yaml` to know baseline 2. SSH to host, run `docker inspect` for the running container, capture RepoDigest 3. Read runbook (if exists) for user-facing context 4. Fill v2 fields per "What done looks like" checklist 5. Validate locally via jsonschema before opening PR 6. Run `tests/smoke.sh traefik` — should still pass (this PR shouldn't change runtime behavior) ## Escape hatch - If `image_observed` from runtime differs from current manifest: STOP, comment on this issue with the discrepancy. Do NOT silently fix manifest — that's a separate decision (manifest correction vs runtime drift). - If runbook claims behavior the module doesn't actually do: STOP, comment. - If module is on a different host than runbook claims: STOP, comment. ## Risk class - [x] `risk/process` — incorrect v2 manifest blocks platformctl validate; downstream blocks Phase 03 ## Dependencies - **Depends on Issue #63** (platformctl validate jsonschema) — until #63 lands, agent uses `python3 -m jsonschema` directly - **Depends on Issue #66** (L4-Verify suite) — once #66 lands, this PR auto-validated end-to-end ## Trace - Parent meta-issue: #70 - Priority rank: 7/8 per #70 heuristic - Decomposed by: claude (orchestrator), 2026-05-06 - Per agent-execution-template.md: spec sources whitelist + extracted context + allowed touched paths + escape hatch

claude added the

phase/02

proposed

labels

2026-05-06 00:26:44 +02:00

claude referenced this issue

2026-05-06 00:27:25 +02:00

[meta] Phase 02 v2 cataloging — first 5-10 priority modules to v2 #70

codex commented

2026-05-09 01:05:52 +02:00

Collaborator

Role: executor
Intent: checkpoint
Needs owner: yes

Issue #103 is blocked. I verified the Traefik container is running and its image digest matches runtime, but tests/smoke.sh traefik fails because the current manifest health URL https://traefik.pdurlej.com/health returns 404. I also checked /ping, /api/rawdata, and /dashboard/; those returned 404 through the public route.

I did not open a PR that would fake health by setting expected status to 404. This needs either a real Traefik health endpoint, a smoke-extra check, or an owner/orchestrator decision that Traefik health should be represented differently.

Next: define the correct Traefik health signal, then re-run #103.

**Role:** executor **Intent:** checkpoint **Needs owner:** yes Issue #103 is blocked. I verified the Traefik container is running and its image digest matches runtime, but `tests/smoke.sh traefik` fails because the current manifest health URL `https://traefik.pdurlej.com/health` returns 404. I also checked `/ping`, `/api/rawdata`, and `/dashboard/`; those returned 404 through the public route. I did not open a PR that would fake health by setting expected status to 404. This needs either a real Traefik health endpoint, a smoke-extra check, or an owner/orchestrator decision that Traefik health should be represented differently. **Next:** define the correct Traefik health signal, then re-run #103.

codex referenced this issue

2026-05-09 01:06:16 +02:00

[meta] Phase 02 v2 cataloging — first 5-10 priority modules to v2 #70

claude referenced this issue

2026-05-09 23:44:14 +02:00

docs(prompts): codex cleanup prompt — #122 + #124 + #100 (combined) #136

codex added this to the 05 - Platform modularity foundation milestone

2026-05-19 08:36:23 +02:00

codex referenced this issue

2026-05-28 01:21:53 +02:00

chore(m05): triage modularity foundation backlog after ADR-0021/0022 #540

codex commented

2026-05-29 15:58:13 +02:00

Collaborator

M05 disposition: close as completed/superseded by the current Traefik module metadata.

Evidence checked:

modules/traefik/module.yaml now has source/artifact metadata, intent, runtime host/compose service, observed digest, statefulness, exposure, health, and links.
The remaining runtime/update risk belongs to M09 upgrade packets, not this old Phase 02 v2 cataloging pilot.

No module change needed here.

M05 disposition: close as completed/superseded by the current Traefik module metadata. Evidence checked: - `modules/traefik/module.yaml` now has source/artifact metadata, intent, runtime host/compose service, observed digest, statefulness, exposure, health, and links. - The remaining runtime/update risk belongs to M09 upgrade packets, not this old Phase 02 v2 cataloging pilot. No module change needed here.

codex closed this issue

2026-05-29 15:58:14 +02:00

codex referenced this issue

2026-05-29 15:58:16 +02:00

chore(m05): triage modularity foundation backlog after ADR-0021/0022 #540