feat: mark branch follower migration-only

config/cicd-gitea-actions-poc.yaml

@@ -17,6 +17,25 @@ spec:
     preferredTarget: agentrun-jd01-v02
     decisionGate: env-reuse-must-pass-before-replacement
 
+  migration:
+    issue: https://github.com/pikasTech/unidesk/issues/1549
+    primaryEntrypoint: bun scripts/cli.ts cicd gitea-actions-poc plan
+    replacementTarget: gitea-actions-driven-cicd
+    branchFollower:
+      status: deprecated
+      mode: migration-only
+      reason: self-maintained branch observation and controller state machine are being replaced by Gitea mirror and Gitea Actions.
+      allowedDuringMigration:
+        - read-only-status
+        - debug-migration-evidence
+        - existing-production-controller-until-cutover
+      frozenCapabilities:
+        - new-controller-loop-features
+        - new-self-maintained-branch-observer
+        - source-commit-driven-big-loop-debugging
+        - new-fallbacks-around-gitea-actions
+      finalDisposition: remove-apply-run-once-or-convert-to-readonly-archive-after-cutover
+
   sourceAuthority:
     mode: immutable-snapshot-ref
     allowMutableBranchAsCiSource: false

scripts/src/cicd-gitea-actions-poc.ts

@@ -187,6 +187,7 @@ function buildPlan(loaded: LoadedPoc, options: Options): Record<string, unknown>
     phase: stringOrNull(scope?.phase),
     rolloutEnabled: scope?.rolloutEnabled === true,
     productionFollowerReplacement: scope?.productionFollowerReplacement === true,
+    migration: compactMigration(optionalRecord(loaded.spec.migration)),
     sourceAuthority: compactSourceAuthority(optionalRecord(loaded.spec.sourceAuthority)),
     planes: [
       compactRuntimePlane(optionalRecord(loaded.spec.runtimePlane)),
@@ -248,6 +249,23 @@ function compactSourceAuthority(value: Record<string, unknown> | null): Record<s
   };
 }
 
+function compactMigration(value: Record<string, unknown> | null): Record<string, unknown> {
+  const branchFollower = optionalRecord(value?.branchFollower);
+  return {
+    issue: stringOrNull(value?.issue),
+    primaryEntrypoint: stringOrNull(value?.primaryEntrypoint),
+    replacementTarget: stringOrNull(value?.replacementTarget),
+    branchFollower: {
+      status: stringOrNull(branchFollower?.status),
+      mode: stringOrNull(branchFollower?.mode),
+      reason: stringOrNull(branchFollower?.reason),
+      allowedDuringMigration: stringArray(branchFollower?.allowedDuringMigration),
+      frozenCapabilities: stringArray(branchFollower?.frozenCapabilities),
+      finalDisposition: stringOrNull(branchFollower?.finalDisposition),
+    },
+  };
+}
+
 function compactRuntimePlane(value: Record<string, unknown> | null): Record<string, unknown> {
   return {
     plane: "runtime",
@@ -359,6 +377,8 @@ function renderPlanHuman(payload: Record<string, unknown>): string {
   const next = optionalRecord(payload.next);
   const planes = arrayRecords(payload.planes);
   const reuse = optionalRecord(payload.reuse);
+  const migration = optionalRecord(payload.migration);
+  const branchFollower = optionalRecord(migration?.branchFollower);
   const statusProjection = optionalRecord(payload.statusProjection);
   const errors = stringArray(payload.errors);
   const warnings = stringArray(payload.warnings);
@@ -379,6 +399,10 @@ function renderPlanHuman(payload: Record<string, unknown>): string {
     "SOURCE AUTHORITY",
     sourceAuthorityLine(optionalRecord(payload.sourceAuthority)),
     "",
+    "MIGRATION POLICY",
+    `replacement=${migration?.replacementTarget ?? "-"} primary=${migration?.primaryEntrypoint ?? "-"} branchFollower=${branchFollower?.status ?? "-"}:${branchFollower?.mode ?? "-"}`,
+    `frozen=${stringArray(branchFollower?.frozenCapabilities).join(",") || "-"}`,
+    "",
     table(["PLANE", "DOCKER", "BUILDS", "MODE", "ENGINE", "MASTER", "RUNTIME_NODE", "AUTHORITY"], planes.map((plane) => [
       plane.plane,
       boolText(plane.dockerAllowed),
@@ -413,11 +437,14 @@ function renderPlanHuman(payload: Record<string, unknown>): string {
 
 function renderStatusHuman(payload: Record<string, unknown>): string {
   const next = optionalRecord(payload.next);
+  const migration = optionalRecord(payload.migration);
+  const branchFollower = optionalRecord(migration?.branchFollower);
   const errors = stringArray(payload.errors);
   return [
     `CI/CD GITEA-ACTIONS POC STATUS (${payload.ok === false ? "blocked" : "declared-only"})`,
     "",
     `statusSource=${payload.statusSource ?? "-"} mode=${payload.statusMode ?? "-"}`,
+    `replacement=${migration?.replacementTarget ?? "-"} branchFollower=${branchFollower?.status ?? "-"}:${branchFollower?.mode ?? "-"}`,
     "",
     table(["TARGET", "SOURCE", "GITEA", "ACTIONS", "TEKTON", "BUILDER", "ARGO", "RUNTIME", "REUSE"], arrayRecords(payload.checks).map((check) => [
       check.target,

scripts/src/cicd-help.ts

@@ -4,6 +4,10 @@
 export function buildCicdHelp(configPath: string, spec: string): unknown {
   return {
     command: "cicd branch-follower plan|apply|status|run-once|debug-step|cleanup-state|events|logs|taskrun|job|runtime|gate",
+    deprecated: true,
+    mode: "migration-only",
+    replacement: "bun scripts/cli.ts cicd gitea-actions-poc plan",
+    issue: "https://github.com/pikasTech/unidesk/issues/1549",
     output: "text by default; use --json, --raw, or -o json|yaml for machine output",
     usage: [
       "bun scripts/cli.ts cicd branch-follower plan",
@@ -27,6 +31,6 @@ export function buildCicdHelp(configPath: string, spec: string): unknown {
     ],
     config: configPath,
     spec,
-    description: "Deploy and inspect the YAML-first Kubernetes branch follower that follows HWLAB v0.3, AgentRun v0.2, and the selected web-probe sentinel master lane without using host worktrees as source authority.",
+    description: "Deprecated migration-only branch follower controller. Existing production status/debug remains available during cutover, but new CI/CD replacement work should use Gitea mirror and Gitea Actions.",
   };
 }

scripts/src/cicd-render.ts

@@ -52,6 +52,10 @@ function renderPlanHuman(payload: Record<string, unknown>): string {
   return [
     `CI/CD BRANCH-FOLLOWER PLAN (${payload.ok === false ? "blocked" : "ok"})`,
     "",
+    "DEPRECATION",
+    "branch-follower=migration-only replacement=\"bun scripts/cli.ts cicd gitea-actions-poc plan\" issue=https://github.com/pikasTech/unidesk/issues/1549",
+    "Do not add new branch-follower controller-loop features; use the Gitea Actions driven path from #1548/#1549.",
+    "",
     table(["FOLLOWER", "ENABLED", "ADAPTER", "SOURCE", "TARGET", "BUDGET", "REFS", "CHECKS"], rows),
     "",
     "SOURCE AUTHORITY",

scripts/src/cicd.ts

@@ -8,11 +8,17 @@ import { cicdGiteaActionsPocHelp, runGiteaActionsPocCommand } from "./cicd-gitea
 
 export function cicdHelp(): unknown {
   return {
-    command: "cicd branch-follower|gitea-actions-poc",
+    command: "cicd gitea-actions-poc|branch-follower",
     output: "text by default for subcommands; top-level help is json",
+    migration: {
+      issue: "https://github.com/pikasTech/unidesk/issues/1549",
+      primary: "cicd gitea-actions-poc",
+      deprecated: "cicd branch-follower",
+      note: "New CI/CD replacement work should use the Gitea Actions driven path; branch-follower is migration-only.",
+    },
     subcommands: [
-      branchFollowerHelp(),
       cicdGiteaActionsPocHelp(),
+      branchFollowerHelp(),
     ],
   };
 }
@@ -22,5 +28,5 @@ export async function runCicdCommand(config: UniDeskConfig | null, args: string[
   if (top === undefined || top === "help" || top === "--help" || top === "-h") return renderMachine("cicd", cicdHelp(), "json");
   if (top === "branch-follower") return await runBranchFollowerCommand(config, args);
   if (top === "gitea-actions-poc" || top === "gitea-builder-poc") return await runGiteaActionsPocCommand(config, args.slice(1), top);
-  throw new Error("cicd usage: cicd branch-follower|gitea-actions-poc");
+  throw new Error("cicd usage: cicd gitea-actions-poc|branch-follower");
 }

scripts/src/help.ts

@@ -58,8 +58,8 @@ export function rootHelp(): unknown {
       { command: "decision requirement list|create|show|update|upsert [id|docNo] [--title text] [--body-file path] [--type external_goal|internal_goal|goal|decision|blocker|debt|experiment] [--doc-no DC-...] [--doc-type ...] [--doc-priority P0|P1|P2|P3] [--signer text] [--issued-at ISO]", description: "Manage productized requirement records over the PostgreSQL records model, excluding meeting records." },
       { command: "decision show <id|docNo>", description: "Show one Decision Center record." },
       { command: "deploy check|plan|apply [--file deploy.json|--env dev|prod] [--service id] [--commit full-sha] [--dry-run] [--force]", description: "Reconcile services from origin/master:deploy.json environments; --commit overrides one reviewed artifact consumer such as frontend for release/v1 validation or rollback. code-queue artifact consumption is dev-only." },
-      { command: "cicd branch-follower plan|apply|status|run-once|events|logs", description: "Deploy and inspect the YAML-first Kubernetes branch follower for HWLAB v0.3, AgentRun v0.2, and web-probe sentinel master without using host worktrees as source authority." },
-      { command: "cicd gitea-actions-poc plan|status", description: "Inspect the GH-1548 Gitea mirror/Actions visibility and controlled Docker/BuildKit builder-plane POC plan while keeping runtime plane 0 Docker and env reuse as a P0 no-regression contract." },
+      { command: "cicd gitea-actions-poc plan|status", description: "Recommended CI/CD migration path for GH-1548/GH-1549: Gitea mirror and Gitea Actions driven orchestration with controlled Docker/BuildKit builder-plane, runtime plane 0 Docker and env reuse as a P0 no-regression contract." },
+      { command: "cicd branch-follower plan|apply|status|run-once|events|logs", description: "Deprecated migration-only Kubernetes branch follower controller; keep existing production status/debug during cutover, but do not add new self-maintained branch-following features." },
       { command: "dev-env validate|prewarm-images", description: "Validate D601 unidesk-dev guardrails or prewarm dev foundation images into native k3s containerd through a bounded async job." },
       { command: "artifact-registry plan|render|status|health|install|deploy-backend-core|deploy-service", description: "Manage the D601 host-managed CNCF Distribution registry and run pull-only artifact CD for supported services, including D601 direct, k3s-managed, and code-queue dev-only consumers." },
       { command: "auth-broker contract|health --dry-run|credential-request --dry-run|pr-preflight --dry-run", description: "Inspect the P0 Rust auth broker and CLI adapter contract without reading token values, writing GitHub, or starting services." },
@@ -735,17 +735,15 @@ function webProbeHelpSummary(): unknown {
 
 function cicdHelpSummary(): unknown {
   return {
-    command: "cicd branch-follower ... | gitea-actions-poc plan|status",
+    command: "cicd gitea-actions-poc plan|status | branch-follower ...",
     output: "text by default; use --json, --raw, or -o json|yaml for machine output",
     usage: [
-      "bun scripts/cli.ts cicd branch-follower plan",
-      "bun scripts/cli.ts cicd branch-follower apply --confirm --wait",
-      "bun scripts/cli.ts cicd branch-follower status",
-      "bun scripts/cli.ts cicd branch-follower run-once --all --dry-run",
       "bun scripts/cli.ts cicd gitea-actions-poc plan",
       "bun scripts/cli.ts cicd gitea-actions-poc status",
+      "bun scripts/cli.ts cicd branch-follower plan",
+      "bun scripts/cli.ts cicd branch-follower status",
     ],
-    description: "YAML-first Kubernetes branch follower plus the GH-1548 read-only Gitea mirror/Actions and controlled builder-plane POC.",
+    description: "Gitea Actions driven CI/CD migration path; branch-follower remains deprecated migration-only status/debug during cutover.",
   };
 }