pikasTech-unidesk/docs/issue/issue-9-k3s-user-service-cicd-state.md

# Issue 9 K3s User-Service CI/CD State

Snapshot date: 2026-05-21

This matrix closes the current review pass for the `decision-center`, `mdtodo`, `claudeqq`, `todo-note`, `project-manager` and frontend artifact lane. It records only focused smoke evidence: health, runtime commit/digest or deployment labels, private proxy API checks and registry artifact presence. No full e2e/Playwright run, backend-core restart, Code Queue restart, backend-core prod deploy, frontend deploy, publish, or Code Queue prod deploy is part of this lane.

## Shared Findings

| Area | State | Impact | Next step |
| --- | --- | --- | --- |
| Artifact producer catalog | `CI.json` has source-build producer entries for the reviewed services, including `frontend`. | The standard producer route is modeled for the lane. | Keep producer commands as the only source-build entrypoint: `ci publish-user-service --service <id> --commit <full-sha>`. |
| CD consumer plan | `deploy plan --env dev|prod --service <id>` and `deploy apply --env dev|prod --service <id> --dry-run` resolve standard consumers: k3s-managed for `decision-center`, `mdtodo`, `claudeqq` and dev `frontend`; main-server Compose artifact consumer for `todo-note` and prod `frontend`. | The dry-run contract exists on both entrypoints, but live apply still depends on artifact and verification readiness. | Use dev -> focused smoke -> prod only after the desired artifact exists and the preflight channel is healthy. |
| Artifact-registry probe | Remote frontend Host SSH probing is no longer blocked by command length. Registry runtime API is reachable and frontend publish dry-run can report ready, while `artifact-registry health` still reports service drift in rendered config / registry image scopes. | Runtime artifact reads are usable for contract evidence; registry service drift remains an infra hygiene item and should not be confused with a frontend publish blocker. | Repair registry rendered-config/image drift separately before treating registry health as fully clean. |
| Project-manager registry probe | `deploy.json` wants `0c3cdb4ee06a23361ed511a2da033d67b53d16f4`; `config.json` still records runtime commit `a278de032d5cdb91010466ac1e2183c79026550d`; remote registry HEAD for `127.0.0.1:5000/unidesk/project-manager:0c3cdb4ee06a23361ed511a2da033d67b53d16f4` returned 404, so no digest is available yet. | The producer and consumer contract is wired, but the desired artifact is still missing. | Publish the desired artifact before any live dev or prod apply. |
| Dev service catalog | `decision-center-dev` exists in k3s, while `mdtodo-dev` and `claudeqq-dev` do not. The adapter public catalog did not expose the dev aliases during this pass. | Dev promotion cannot be claimed for `mdtodo` or `claudeqq`; `decision-center-dev` is reachable through direct k3s service proxy only. | Publish artifacts first, then create/verify dev consumers and register dev aliases where intended. |
| Frontend closure contract | `bun scripts/frontend-artifact-lane-contract-test.ts` is the standard lightweight contract for the frontend artifact sample. | Frontend lane evidence is now repeatable without live deploy, publish, service restart, or Playwright. | Keep the contract green whenever frontend deploy.json, health metadata, artifact digest, producer preflight, or CD dry-run shape changes. |
| User-service gap contract | `bun scripts/issue-9-user-service-artifact-gap-contract-test.ts` normalizes `mdtodo`, `claudeqq` and `todo-note` with `desiredCommit`, `runtimeCommit`, `artifactExists`, `devStatus`, `prodStatus`, `blockedScopes` and `recommendedAction`; `bun scripts/issue-9-user-service-deploy-apply-dry-run-contract-test.ts` covers the top-level `deploy apply --env dev|prod --service <id> --dry-run` envelope for the same three services. | The remaining gap surface is repeatable from `deploy.json`, `CI.json`, `deploy apply --dry-run` and local artifact-registry dry-runs without publish, deploy, service restart, or full check/e2e. | Keep both contracts green when desired commits, producer metadata, consumer targets or next-hop classifications change. |

## Service Matrix

| Service | Desired artifact | Deployment and CI shape | Dev acceptance | Prod acceptance | Ideal-state status | Blockers / next step |
| --- | --- | --- | --- | --- | --- | --- |
| `decision-center` | `127.0.0.1:5000/unidesk/decision-center:b5486a61ab0aa6c227366a95d1afa68281584359`, registry digest `sha256:55ae6b20af3b6ec88394de46678cd4ddf86c461126ee1e95e91005baf72f03ed`. Previous desired tag `54c1f8e165f90fa8509fda1f0c01f8c3fa82cbee` still exists with digest `sha256:8af6842a2a1b23bfaf6067a402821f4d0e54b76ebc24e59303c6cbefad6490d1`, but it is no longer the desired state. | k3s-managed artifact consumer on D601. CI producer is UniDesk source-build from `src/components/microservices/decision-center/Dockerfile`; CD dry-run is a no-build D601 k3s artifact consumer for dev and prod. | `unidesk-dev/decision-center-dev` is ready 1/1 and health reports `deploy.commit` / `deploy.requestedCommit` as `b5486a61ab0aa6c227366a95d1afa68281584359`, matching desired and artifact. | `unidesk/decision-center` is ready 1/1 and health reports `deploy.commit` / `deploy.requestedCommit` as `b5486a61ab0aa6c227366a95d1afa68281584359`; private proxy `/api/records?limit=1` returned 200. | Complete for artifact CD contract. Dev/prod desired, live health and registry artifact now align on `b5486a61ab0aa6c227366a95d1afa68281584359`; no deploy was needed. | Remaining work is manual UI/product acceptance only: record CRUD, diary lifecycle, doc-number uniqueness and frontend Decision Center visibility. Keep the desired-state contract green so future edits cannot reintroduce stale desired commits or source-build CD. |
| `mdtodo` | `127.0.0.1:5000/unidesk/mdtodo:595de3d320b73ec006794440b32db48b3ad14d2b`; registry artifact still needs publication. The previous `75fb6757b2504ba86d61f2587fb34a9c9ed4019a` target predates `mdtodo` health deploy metadata. | k3s-managed artifact consumer on D601. CI producer is UniDesk source-build from `src/components/microservices/mdtodo/Dockerfile`. | `unidesk-dev/mdtodo-dev` does not exist. | `unidesk/mdtodo` is ready 1/1 at the old annotated commit `75fb6757b2504ba86d61f2587fb34a9c9ed4019a`; health returned `ok=true`, and `/live` returned 200 during the earlier smoke. Runtime health metadata still needs proof after the new artifact is deployed. | Partial. The source/desired contract now points at a health-metadata-capable commit, but the desired registry artifact is absent, dev is absent and prod runtime is intentionally behind the new desired commit. | Publish the new desired artifact, create/verify `unidesk-dev/mdtodo-dev`, prove `/health.deploy.commit` and `/live.deploy.commit` in dev, then decide whether prod needs artifact replacement. |
| `claudeqq` | `127.0.0.1:5000/unidesk/claudeqq:203b1f46684c91340ecbbd8a74502bd55e4f2011`; registry HEAD returned 404, so no digest was available. | k3s-managed artifact consumer on D601. CI producer uses the external Gitee source plus UniDesk adapter/overlay. | `unidesk-dev/claudeqq-dev` does not exist. | `unidesk/claudeqq` is ready 1/1. Deployment annotations and `/health` report commit/requested commit `203b1f46684c91340ecbbd8a74502bd55e4f2011`; health also reports NapCat `logged_in`. Focused API probes for `/api/events/recent` and `/api/events/subscriptions` returned 404. | Partial. Prod commit alignment and health are good, but the desired registry artifact is absent, dev is absent and the expected event API surface is not verified. | Publish the desired artifact, create/verify dev, and either fix or document the current event API paths before any prod artifact replacement. |
| `todo-note` | `127.0.0.1:5000/unidesk/todo-note:a14ce0eb855a685fa17b47adacd54623e72cd2ff`; registry HEAD returned 404, so no digest was available. | Main-server Compose artifact consumer. CI producer uses the external Gitee source. CD plan is pull-only and no-build for Compose service `todo-note`, container `todo-note-backend`. | The dev/prod consumer plans resolve, but no live dev apply was attempted because the desired artifact is absent. | Runtime health returned 200 with PostgreSQL storage and running reminders. Private proxy `/api/instances` returned 200. The running container image is `unidesk-todo-note`; runtime labels do not expose `unidesk.ai/source-commit`, and health does not expose deploy metadata. | Not yet. Runtime behavior is healthy, but image digest/commit proof is missing and the desired registry artifact is absent. | Publish the desired artifact, then use the Compose artifact consumer to recreate only `todo-note` with no build/no deps and verify image labels plus health deploy metadata. |
| `project-manager` | `127.0.0.1:5000/unidesk/project-manager:0c3cdb4ee06a23361ed511a2da033d67b53d16f4`; registry HEAD returned 404, so no digest was available. Current runtime registry commit in `config.json` is `a278de032d5cdb91010466ac1e2183c79026550d`. | Main-server Compose artifact consumer. CI producer is UniDesk source-build from `src/components/microservices/project-manager/Dockerfile`. | `deploy plan --env dev --service project-manager` resolves the same no-build main-server Compose path; no live dev apply was attempted because the desired artifact is absent. | `deploy plan --env prod --service project-manager --dry-run` resolves the same main-server Compose consumer and health contract, but live prod apply remains blocked until the artifact exists and `/health` can report `deploy.commit` / `deploy.requestedCommit`. | Partial. The source and consumer contract are in place; the registry artifact is not. | Publish `0c3cdb4ee06a23361ed511a2da033d67b53d16f4` to the D601 registry, then run dev and prod artifact-consumer verification. |
| `frontend` | `127.0.0.1:5000/unidesk/frontend:b5486a61ab0aa6c227366a95d1afa68281584359`, registry v2 manifest digest `sha256:76d7c47e797605470959ca2274f116149bdc367e6fa155913d19f42516e5b9e4`. | CI producer is `ci publish-user-service` from `src/components/frontend/Dockerfile`. Dev CD is D601 native k3s `frontend-dev`; prod CD is master-server Compose `frontend` / `unidesk-frontend`; both are pull-only artifact consumers. | Public dev `http://74.48.78.17:18083/health` reports `ok=true`, `environment=dev`, `namespace=unidesk-dev`, and deploy commit/requestedCommit `b5486a61ab0aa6c227366a95d1afa68281584359`. | Public prod `http://74.48.78.17:18081/health` reports `ok=true` and deploy commit/requestedCommit `b5486a61ab0aa6c227366a95d1afa68281584359`. Remote `ci publish-user-service --service frontend --commit b5486... --dry-run` reports `runnerDisposition=ready`, all control channels ready, and no missing control channels. | Complete for CI/CD contract. Dev/prod desired and live commit match the artifact; CD dry-runs are non-mutating and no-build. | Remaining UI route acceptance is a manual product/UI gate and is independent of CI/CD artifact correctness. |

## Normalized Gap Matrix

Focused read-only evidence for this refresh:

- remote `microservice status` and `microservice health` for `mdtodo`, `claudeqq` and `todo-note`;
- D601 registry v2 manifest `HEAD` against each desired tag, all returning 404;
- `deploy plan --env dev|prod --service <id>`, `deploy apply --env dev|prod --service <id> --dry-run` and `artifact-registry deploy-service --env dev|prod --service <id> --commit <desiredCommit> --dry-run`, all resolving no-build artifact consumers.

| Service | desiredCommit | runtimeCommit | artifactExists | devStatus | prodStatus | blockedScopes | recommendedAction |
| --- | --- | --- | --- | --- | --- | --- | --- |
| `mdtodo` | `595de3d320b73ec006794440b32db48b3ad14d2b` | `75fb6757b2504ba86d61f2587fb34a9c9ed4019a` from prod Deployment annotations; that runtime predates `mdtodo` health deploy metadata | `false` | `missing-dev-service` | `healthy-prod-annotation-stale-after-health-metadata-repin` | `registry-artifact`, `dev-service`, `runtime-health-metadata-proof`, `prod-runtime-commit-drift` | Publish the desired artifact that includes `mdtodo` health deploy metadata, create/verify `unidesk-dev/mdtodo-dev`, then run focused dev smoke before deciding whether prod needs replacement. |
| `claudeqq` | `203b1f46684c91340ecbbd8a74502bd55e4f2011` | `203b1f46684c91340ecbbd8a74502bd55e4f2011` from prod `/health.deploy.commit` and `/health.deploy.requestedCommit` | `false` | `missing-dev-service` | `healthy-prod-health-aligned-event-api-unverified` | `registry-artifact`, `dev-service`, `event-api-surface` | Publish the desired artifact, create/verify `unidesk-dev/claudeqq-dev`, then resolve or document the event API paths before prod artifact replacement. |
| `todo-note` | `a14ce0eb855a685fa17b47adacd54623e72cd2ff` | `null`; prod health and container labels do not expose source commit | `false` | `consumer-plan-only-no-live-dev` | `healthy-behavior-no-commit-proof` | `registry-artifact`, `runtime-commit-proof`, `health-deploy-metadata` | Publish the desired artifact, then use the no-build Compose artifact consumer to recreate only `todo-note` and verify image labels plus health deploy metadata. |

Repeatable contracts:

```bash
bun scripts/issue-9-mdtodo-health-metadata-contract-test.ts
bun scripts/issue-9-user-service-artifact-gap-contract-test.ts
bun scripts/issue-9-user-service-deploy-apply-dry-run-contract-test.ts
```

## Execution Decision

No live deployment or publish was executed in this pass.

- `decision-center` drift was desired-state only: dev/prod live health and the registry artifact already matched `b5486a61...`, so `deploy.json` was repinned to that verified commit without deploying.
- `mdtodo`, `claudeqq`, `todo-note` and `project-manager` do not have the desired registry artifact tags, so live apply would not satisfy the artifact-consumer contract. For `mdtodo`, the desired tag is now `595de3d320b73ec006794440b32db48b3ad14d2b` because that is the already-merged commit that adds `/health.deploy` and `/live.deploy`.
- `frontend` is the first batch sample that can be marked complete for the CI/CD artifact lane: desired commit, registry artifact digest, dev/prod health metadata, publish dry-run readiness and dev/prod CD no-build dry-runs are aligned.
- Focused smoke stayed limited to health, deployment metadata, registry HEAD/tag checks and small private proxy API calls.

## MDTODO Next Preconditions

Before a real `mdtodo` artifact publish or dev deploy:

- Run the read-only publish preflight for `595de3d320b73ec006794440b32db48b3ad14d2b`: `bun scripts/cli.ts ci publish-user-service --service mdtodo --commit 595de3d320b73ec006794440b32db48b3ad14d2b --dry-run`. It must report `runnerDisposition=ready` or clearly classify only infrastructure blockers.
- Publish only from the controlled D601 CI path: `bun scripts/cli.ts ci publish-user-service --service mdtodo --commit 595de3d320b73ec006794440b32db48b3ad14d2b --wait-ms 1200000`.
- Record the resulting `artifactSummary.imageRef`, `digest` and `digestRef`; verify registry `HEAD /v2/unidesk/mdtodo/manifests/595de3d320b73ec006794440b32db48b3ad14d2b` returns a digest.
- Keep `deploy apply --env dev --service mdtodo --dry-run` on the D601 k3s no-build artifact consumer and confirm it targets only `unidesk-dev/mdtodo-dev`.
- Run real dev apply only after the artifact exists, then verify `unidesk-dev/mdtodo-dev` readiness and service-proxy `/health.deploy.commit`, `/health.deploy.requestedCommit`, `/live.deploy.commit` all equal `595de3d320b73ec006794440b32db48b3ad14d2b`.
- Evaluate prod replacement only after dev proof is recorded; prod currently runs the older annotated `75fb6757b2504ba86d61f2587fb34a9c9ed4019a` runtime.