test: add frontend artifact lane contract

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

@@ -2,16 +2,17 @@
 
 Snapshot date: 2026-05-21
 
-This matrix closes the current review pass for the `decision-center`, `mdtodo`, `claudeqq` and `todo-note` 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 or Code Queue prod deploy is part of this lane.
+This matrix closes the current review pass for the `decision-center`, `mdtodo`, `claudeqq`, `todo-note` 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 all four services. | The standard producer route is modeled for the whole 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>` resolves standard consumers for all four services: k3s-managed for `decision-center`, `mdtodo`, `claudeqq`; main-server Compose artifact consumer for `todo-note`. | The dry-run contract exists, 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 | Direct D601 registry API access is healthy, but remote frontend `artifact-registry health` and CI publish dry-run registry checks fail because the provider Host SSH command is rejected as too long (`4039` bytes). | The registry itself is reachable from D601, but the standard preflight tool path reports `registry` as infra-blocked. | Split or shrink the registry health probe before relying on remote CI dry-run as release evidence. |
+| 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>` resolves 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, 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. |
 | 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. |
 
 ## Service Matrix
 
@@ -21,11 +22,13 @@ This matrix closes the current review pass for the `decision-center`, `mdtodo`,
 | `mdtodo` | `127.0.0.1:5000/unidesk/mdtodo:75fb6757b2504ba86d61f2587fb34a9c9ed4019a`; registry HEAD returned 404, so no digest was available. | 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. Deployment annotations record deploy and requested commit `75fb6757b2504ba86d61f2587fb34a9c9ed4019a`; health returned `ok=true`, and `/live` returned 200. Health does not expose deploy metadata. | Partial. Prod is healthy and annotated with the desired commit, but the desired registry artifact is absent and dev is absent. | Publish the desired artifact, add deploy metadata to health or keep strict label/annotation verification, then run dev -> focused smoke -> prod if prod replacement is still needed. |
 | `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. |
+| `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. |
 
 ## Execution Decision
 
-No live deployment was executed in this pass.
+No live deployment or publish was executed in this pass.
 
 - `decision-center` has an available desired artifact, but both dev and prod are currently healthy on `b5486a61...`; the task scope asked for review and gap recording unless a repair is clearly safe. The standard remote registry preflight path is currently infra-blocked, so this pass records drift instead of changing prod/dev.
 - `mdtodo`, `claudeqq` and `todo-note` do not have the desired registry artifact tags, so live apply would not satisfy the artifact-consumer contract.
+- `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.

docs/reference/cicd-standardization.md

@@ -268,6 +268,14 @@ This matrix describes the next promotion stage after dry-run coverage is in plac
 | `k3sctl-adapter` | `master` | source-build supported | plan/dry-run only | no normal dev target; only control-bridge health and recovery evidence | prod live apply requires supervisor confirmation | bridge recovery, k3s fault-domain isolation, no worker self-replacement | `GPT-5.5` |
 | `filebrowser` / `filebrowser-d601` | `master` | upstream-image blocked | pull-only mirror target | digest resolution, mirror governance and private proxy health only | not in this phase | upstream digest/mirror worker not yet implemented | `DeepSeek` for evidence summarization, `GPT-5.5` for blocker resolution |
 
+Frontend lane closure evidence is intentionally lightweight and non-mutating:
+
+```bash
+bun scripts/frontend-artifact-lane-contract-test.ts
+```
+
+The contract fixes the current sample around one artifact lane: `deploy.json` dev/prod both request the same frontend commit, `CI.json` keeps the producer as `ci publish-user-service`, the D601 registry manifest digest is recorded, dev and prod health expose matching `deploy.commit` / `deploy.requestedCommit`, `ci publish-user-service --dry-run` is ready, and both CD dry-runs are artifact consumers with no source build.
+
 Planned parallelism for the next wave should be three lanes:
 
 1. Lane A: `frontend`, `baidu-netdisk`, `project-manager`, `oa-event-flow`.

docs/reference/user-service-delivery.md

@@ -65,6 +65,7 @@ Frontend is the canonical user-service UI sample. It is not released by target-s
 
 - The minimal standard artifact command is `bun scripts/cli.ts ci publish-user-service --service frontend --commit <full-sha> --wait-ms 1200000`.
 - The expected artifact is `127.0.0.1:5000/unidesk/frontend:<commit>` plus its registry digest from the CI output.
+- The lightweight closure contract is `bun scripts/frontend-artifact-lane-contract-test.ts`. It checks `deploy.json` dev/prod desired commits, the `CI.json` producer entry, the observed registry digest, dev/prod `/health.deploy.commit` and `deploy.requestedCommit`, producer dry-run readiness, and dev/prod CD dry-run no-build targets.
 - Dev CD consumes the same artifact with `bun scripts/cli.ts deploy apply --env dev --service frontend`; it imports the image into D601 native k3s, rolls out `frontend-dev`, syncs auth/session metadata from main-server config, and verifies `/health.deploy.commit`.
 - Production CD consumes the same artifact with `bun scripts/cli.ts deploy apply --env prod --service frontend`; it recreates only the master-server Compose `frontend` service with `--no-build --no-deps --force-recreate` and verifies image labels plus `/health.deploy.commit`.
 - `server rebuild frontend` remains a maintenance/local rebuild path only. It is not the standard versioned release truth for frontend.