# API Deployment Observation Foundation Implementation Plan

> **Execution note:** Execute this plan task-by-task with the KT-local workflow and use the checkboxes to track plan state.

**Goal:** Build Phase 2 of the approved API Runtime Foundation: a ktWorkflow deployment observation adapter that gathers Jenkins, K8s, Pod, `/health/runtime`, and task smoke evidence before any deployed feature is called complete.

**Architecture:** Keep API runtime health as the source contract and implement the observation workflow in `mcp/ktWorkflow`. The new tool generates a bounded, read-only NAS script by default, can execute it only when `execute=true`, normalizes command output into an API-compatible runtime evidence summary, and writes evidence under `.kt-workspace/test-artifacts/deploy-observation`. Deployment rollout evidence remains separate from functional smoke evidence.

**Tech Stack:** TypeScript ESM, `@modelcontextprotocol/sdk`, Zod, Node `child_process`, PowerShell, `ssh nas`, Kubernetes `kubectl`, Jenkins home/log read-only inspection, `curl`, pnpm.

---

## Current Context

- API repo: `D:\MyFiles\KT\Node\kt-template-online-api`, branch `dev`, currently clean at the time this plan was written.
- ktWorkflow repo: `D:\MyFiles\KT\mcp\ktWorkflow`, branch `main`, currently has pre-existing changes in `README.md`, `src/selfTest.ts`, and `src/tools/review.ts`.
- Do not create a `.worktree`. The user explicitly prefers a normal development branch.
- Do not overwrite the dirty ktWorkflow files. The execution phase must classify or preserve those changes before editing files that overlap this plan.
- API public health contract is already implemented as plain JSON:

```ts
export type RuntimeHealthStatus = 'live' | 'ready' | 'degraded' | 'blocked';

export interface RuntimeHealthCheck {
  name: string;
  status: RuntimeHealthStatus;
  critical: boolean;
  message: string;
  detail?: Record<string, unknown>;
}

export interface RuntimeHealthReport {
  service: 'kt-template-online-api';
  checkedAt: string;
  status: RuntimeHealthStatus;
  checks: RuntimeHealthCheck[];
}
```

## File Structure

- Create `D:\MyFiles\KT\mcp\ktWorkflow\src\tools\deployObservation.ts`
  - Builds the read-only NAS observation command.
  - Parses marked command sections from stdout.
  - Normalizes Jenkins, Deployment, Pod, runtime health, and smoke data into evidence.
  - Writes JSON evidence under `.kt-workspace/test-artifacts/deploy-observation`.

- Modify `D:\MyFiles\KT\mcp\ktWorkflow\src\types.ts`
  - Add `DeployObservationInput`, evidence DTOs, and assertion types.

- Modify `D:\MyFiles\KT\mcp\ktWorkflow\src\core\cli.ts`
  - Add `parseDeployObservationCliArgs(argv)`.

- Modify `D:\MyFiles\KT\mcp\ktWorkflow\src\registerTools.ts`
  - Register MCP tool `kt_deploy_observation`.

- Modify `D:\MyFiles\KT\mcp\ktWorkflow\src\server.ts`
  - Add `--deploy-observation` CLI branch.

- Modify `D:\MyFiles\KT\mcp\ktWorkflow\src\core\constants.ts`
  - Add `kt_deploy_observation` to `registeredToolNames`.

- Modify `D:\MyFiles\KT\mcp\ktWorkflow\src\tools\closeout.ts`
  - Point `deploy-observation` upgrade target to the new tool file.

- Modify `D:\MyFiles\KT\mcp\ktWorkflow\src\selfTest.ts`
  - Add self-tests for CLI parsing, stdout section parsing, evidence normalization, and dry-run command generation.

- Modify `D:\MyFiles\KT\mcp\ktWorkflow\package.json`
  - Add `deploy-observation` script.

- Modify `D:\MyFiles\KT\mcp\ktWorkflow\README.md`
  - Document the new MCP tool and CLI.

- Modify `D:\MyFiles\KT\TASKS.md`
  - Record Phase 2 implementation and verification evidence after code is complete.

## Task 0: Protect Branch And Existing Changes

**Files:**
- Read: `D:\MyFiles\KT\mcp\ktWorkflow\README.md`
- Read: `D:\MyFiles\KT\mcp\ktWorkflow\src\selfTest.ts`
- Read: `D:\MyFiles\KT\mcp\ktWorkflow\src\tools\review.ts`

- [ ] **Step 1: Confirm repo states**

Run:

```powershell
git -C D:\MyFiles\KT\Node\kt-template-online-api status --short --branch
git -C D:\MyFiles\KT\mcp\ktWorkflow status --short --branch
git -C D:\MyFiles\KT status --short --branch
```

Expected:

```text
API repo is on dev and clean.
ktWorkflow repo shows existing modified README.md, src/selfTest.ts, src/tools/review.ts.
Root repo may be dirty from unrelated workspace records.
```

- [ ] **Step 2: Inspect overlapping ktWorkflow changes**

Run:

```powershell
git -C D:\MyFiles\KT\mcp\ktWorkflow diff -- README.md src/selfTest.ts src/tools/review.ts
```

Expected:

```text
The diff is read before edits. Existing hunks are preserved or deliberately carried into the development branch.
```

- [ ] **Step 3: Use a normal development branch**

Run:

```powershell
git -C D:\MyFiles\KT\mcp\ktWorkflow branch --show-current
git -C D:\MyFiles\KT\mcp\ktWorkflow switch -c dev
```

Expected if `dev` does not exist:

```text
Switched to a new branch 'dev'
```

Expected if `dev` already exists:

```powershell
git -C D:\MyFiles\KT\mcp\ktWorkflow switch dev
```

```text
Switched to branch 'dev'
```

- [ ] **Step 4: Stop if switching would overwrite files**

If Git refuses the branch switch because local changes would be overwritten, stop execution and report the exact file list. Do not run `git reset`, `git checkout --`, or any destructive cleanup without explicit user approval.

## Task 1: Add Failing Self-Tests For Deploy Observation

**Files:**
- Modify: `D:\MyFiles\KT\mcp\ktWorkflow\src\selfTest.ts`

- [ ] **Step 1: Add imports that should fail before implementation**

Modify the import area in `src/selfTest.ts`:

```ts
import {
  parseDeployObservationCliArgs,
  parseGlobalReviewCliArgs,
  parseWorkstreamCloseoutCliArgs,
} from "./core/cli.js";
import {
  buildDeployObservation,
  buildDeployObservationSectionMap,
  normalizeDeployObservationEvidence,
} from "./tools/deployObservation.js";
```

- [ ] **Step 2: Add the deploy observation self-test block**

Add this block after the existing workstream closeout self-tests and before the final test artifact write:

```ts
  const deployObservationInput = parseDeployObservationCliArgs([
    "node",
    "server",
    "--deploy-observation",
    "--project",
    "api",
    "--job",
    "kt-template-online-api",
    "--build",
    "132",
    "--commit",
    "abc1234",
    "--image-tag",
    "abc1234",
    "--namespace",
    "kt-prod",
    "--deployment",
    "kt-template-online-api",
    "--container",
    "api",
    "--health-url",
    "http://127.0.0.1:48085/health/runtime",
    "--smoke",
    "curl -fsS --max-time 8 http://127.0.0.1:48085/health/runtime",
  ]);
  if (
    deployObservationInput.project !== "api" ||
    deployObservationInput.jobName !== "kt-template-online-api" ||
    deployObservationInput.buildNumber !== "132" ||
    deployObservationInput.expectedCommit !== "abc1234" ||
    deployObservationInput.imageTag !== "abc1234" ||
    deployObservationInput.namespace !== "kt-prod" ||
    deployObservationInput.deployment !== "kt-template-online-api" ||
    deployObservationInput.container !== "api" ||
    deployObservationInput.healthUrl !==
      "http://127.0.0.1:48085/health/runtime" ||
    deployObservationInput.smoke !==
      "curl -fsS --max-time 8 http://127.0.0.1:48085/health/runtime" ||
    deployObservationInput.execute !== false
  ) {
    throw new Error("deploy observation CLI parser self-check failed");
  }

  const deployObservationSections = buildDeployObservationSectionMap(
    [
      "__KT_SECTION:jenkins_meta__",
      "buildNumber=132",
      "result=SUCCESS",
      "__KT_SECTION:jenkins_log_tail__",
      "Checking out Revision abc1234",
      "Finished: SUCCESS",
      "__KT_SECTION:deployment_json__",
      JSON.stringify({
        metadata: { generation: 12 },
        spec: {
          template: {
            spec: {
              containers: [
                {
                  image:
                    "k3d-kt-registry.localhost:5000/kt-template-online-api:abc1234",
                  name: "api",
                },
              ],
            },
          },
        },
        status: {
          observedGeneration: 12,
          readyReplicas: 1,
          updatedReplicas: 1,
        },
      }),
      "__KT_SECTION:pods_json__",
      JSON.stringify({
        items: [
          {
            metadata: {
              name: "kt-template-online-api-abc",
            },
            spec: {
              containers: [
                {
                  image:
                    "k3d-kt-registry.localhost:5000/kt-template-online-api:abc1234",
                  name: "api",
                },
              ],
            },
            status: {
              containerStatuses: [
                {
                  image:
                    "k3d-kt-registry.localhost:5000/kt-template-online-api:abc1234",
                  name: "api",
                  ready: true,
                  restartCount: 0,
                },
              ],
              phase: "Running",
              startTime: "2026-06-14T00:00:00Z",
            },
          },
        ],
      }),
      "__KT_SECTION:health_json__",
      JSON.stringify({
        checkedAt: "2026-06-14T00:00:01.000Z",
        checks: [
          {
            critical: true,
            message: "NestJS process answered runtime health request",
            name: "process",
            status: "live",
          },
        ],
        service: "kt-template-online-api",
        status: "ready",
      }),
      "__KT_SECTION:smoke_text__",
      "{\"service\":\"kt-template-online-api\",\"status\":\"ready\"}",
    ].join("\n"),
  );
  const deployObservationEvidence = normalizeDeployObservationEvidence({
    checkedAt: new Date("2026-06-14T00:00:02.000Z"),
    input: deployObservationInput,
    sectionMap: deployObservationSections,
  });
  if (
    deployObservationEvidence.status !== "passed" ||
    deployObservationEvidence.details.deployment.image !==
      "k3d-kt-registry.localhost:5000/kt-template-online-api:abc1234" ||
    deployObservationEvidence.details.deployment.observedGeneration !== 12 ||
    deployObservationEvidence.details.pod.name !==
      "kt-template-online-api-abc" ||
    deployObservationEvidence.details.pod.restartCount !== 0 ||
    deployObservationEvidence.details.runtimeHealth.status !== "ready" ||
    !deployObservationEvidence.assertions.every((item) => item.passed)
  ) {
    throw new Error("deploy observation evidence normalization self-check failed");
  }

  const deployObservationDryRun = await buildDeployObservation({
    deployment: "kt-template-online-api",
    execute: false,
    healthUrl: "http://127.0.0.1:48085/health/runtime",
    imageTag: "abc1234",
    jobName: "kt-template-online-api",
    namespace: "kt-prod",
    project: "api",
    smoke: "curl -fsS --max-time 8 http://127.0.0.1:48085/health/runtime",
  });
  const deployObservationCommandText = JSON.stringify(
    deployObservationDryRun.commands,
  );
  if (
    deployObservationDryRun.execute !== false ||
    !deployObservationCommandText.includes("tr -d '\\015' | bash -s") ||
    !deployObservationCommandText.includes("kubectl") ||
    !deployObservationCommandText.includes("/health/runtime") ||
    deployObservationDryRun.evidence
  ) {
    throw new Error("deploy observation dry-run self-check failed");
  }
```

- [ ] **Step 3: Run self-test and confirm the expected failure**

Run:

```powershell
pnpm --dir D:\MyFiles\KT\mcp\ktWorkflow run self-test
```

Expected:

```text
FAIL: Cannot find module './tools/deployObservation.js' or exported member parseDeployObservationCliArgs.
```

- [ ] **Step 4: Commit the red test only if the team wants TDD commits**

Run only when working branch policy allows red commits:

```powershell
git -C D:\MyFiles\KT\mcp\ktWorkflow add src/selfTest.ts
git -C D:\MyFiles\KT\mcp\ktWorkflow commit -m "test: 覆盖部署观测工作流"
```

Expected:

```text
Commit is created on dev, or the red test remains staged for the green implementation commit.
```

## Task 2: Add Deploy Observation Types

**Files:**
- Modify: `D:\MyFiles\KT\mcp\ktWorkflow\src\types.ts`

- [ ] **Step 1: Add deploy observation status and input types**

Insert after `RemoteHealthCheckInput`:

```ts
export type DeployObservationStatus =
  | 'passed'
  | 'failed'
  | 'blocked'
  | 'skipped';

export interface DeployObservationInput {
  artifactRoot?: string;
  buildNumber?: string;
  container?: string;
  deployment?: string;
  execute?: boolean;
  expectedCommit?: string;
  healthUrl?: string;
  imageTag?: string;
  jobName?: string;
  jenkinsHome?: string;
  kubeconfigPath?: string;
  namespace?: string;
  project?: string;
  selector?: string;
  smoke?: string;
  sshPort?: number;
  sshTarget?: string;
}
```

- [ ] **Step 2: Add evidence DTOs**

Insert after `DeployObservationInput`:

```ts
export interface DeployObservationAssertion {
  critical: boolean;
  message: string;
  name: string;
  passed: boolean;
}

export interface DeployObservationCommand {
  command: string;
  name: string;
}

export interface DeployObservationJenkinsEvidence {
  buildNumber: string | null;
  commitMatched: boolean | null;
  expectedCommit: string | null;
  finishedStatus: string | null;
  jobName: string;
}

export interface DeployObservationDeploymentEvidence {
  container: string;
  containerFound: boolean;
  desiredReplicas: number | null;
  generation: number | null;
  image: string | null;
  namespace: string;
  observedGeneration: number | null;
  readyReplicas: number | null;
  updatedReplicas: number | null;
}

export interface DeployObservationPodEvidence {
  containerFound: boolean;
  image: string | null;
  name: string | null;
  phase: string | null;
  ready: boolean | null;
  restartCount: number | null;
}

export interface DeployObservationRuntimeHealthEvidence {
  checkCount: number | null;
  service: string | null;
  status: string | null;
}

export interface DeployObservationEvidence {
  assertions: DeployObservationAssertion[];
  details: {
    deployment: DeployObservationDeploymentEvidence;
    eventsTail: string;
    jenkins: DeployObservationJenkinsEvidence;
    pod: DeployObservationPodEvidence;
    runtimeHealth: DeployObservationRuntimeHealthEvidence;
    smoke: {
      command: string | null;
      output: string;
    };
  };
  endedAt: string;
  environment: 'production';
  operation: 'kt_deploy_observation';
  project: string;
  schemaVersion: 1;
  startedAt: string;
  status: DeployObservationStatus;
  target: string;
  taskType: 'deploy';
  title: string;
}

export interface DeployObservationResult {
  artifactPath?: string;
  commands: DeployObservationCommand[];
  evidence?: DeployObservationEvidence;
  execute: boolean;
  notes: string[];
  requiredEvidence: string[];
  result?: ExecResult;
}
```

- [ ] **Step 3: Run typecheck and confirm the expected failure**

Run:

```powershell
pnpm --dir D:\MyFiles\KT\mcp\ktWorkflow run typecheck
```

Expected:

```text
FAIL because deployObservation.ts and parseDeployObservationCliArgs are not implemented yet.
```

## Task 3: Implement The Deploy Observation Tool

**Files:**
- Create: `D:\MyFiles\KT\mcp\ktWorkflow\src\tools\deployObservation.ts`

- [ ] **Step 1: Create the tool file**

Create `src/tools/deployObservation.ts` with this implementation:

```ts
import { mkdirSync, writeFileSync } from 'node:fs';
import path from 'node:path';

import type {
  DeployObservationAssertion,
  DeployObservationCommand,
  DeployObservationDeploymentEvidence,
  DeployObservationEvidence,
  DeployObservationInput,
  DeployObservationJenkinsEvidence,
  DeployObservationPodEvidence,
  DeployObservationResult,
  DeployObservationRuntimeHealthEvidence,
  DeployObservationStatus,
} from '../types.js';
import { tryPowerShell } from '../core/exec.js';
import {
  formatDateInShanghai,
  resolveInsideRoot,
  workspaceRoot,
} from '../core/workspace.js';

interface NormalizedInput extends Required<
  Pick<
    DeployObservationInput,
    | 'artifactRoot'
    | 'container'
    | 'deployment'
    | 'healthUrl'
    | 'jenkinsHome'
    | 'jobName'
    | 'kubeconfigPath'
    | 'namespace'
    | 'project'
    | 'selector'
    | 'sshPort'
    | 'sshTarget'
  >
> {
  buildNumber?: string;
  execute: boolean;
  expectedCommit?: string;
  imageTag?: string;
  smoke?: string;
}

interface NormalizeEvidenceInput {
  checkedAt?: Date;
  input: DeployObservationInput;
  sectionMap: Map<string, string>;
}

function normalizeInput(input: DeployObservationInput = {}): NormalizedInput {
  return {
    artifactRoot:
      input.artifactRoot || '.kt-workspace/test-artifacts/deploy-observation',
    buildNumber: input.buildNumber?.trim() || undefined,
    container: input.container?.trim() || 'api',
    deployment: input.deployment?.trim() || 'kt-template-online-api',
    execute: input.execute === true,
    expectedCommit: input.expectedCommit?.trim() || undefined,
    healthUrl:
      input.healthUrl?.trim() ||
      'http://127.0.0.1:48085/health/runtime',
    imageTag: input.imageTag?.trim() || undefined,
    jenkinsHome: input.jenkinsHome?.trim() || '/vol1/docker/jenkins/jenkins_home',
    jobName: input.jobName?.trim() || 'KT-Template/KT-Template-API/main',
    kubeconfigPath:
      input.kubeconfigPath?.trim() ||
      '/vol1/docker/kt-k8s/kubeconfig/kt-nas.jenkins.yaml',
    namespace: input.namespace?.trim() || 'kt-prod',
    project: input.project?.trim() || 'api',
    selector:
      input.selector?.trim() || 'app=kt-template-online-api',
    smoke: input.smoke?.trim() || undefined,
    sshPort: input.sshPort || 2202,
    sshTarget: input.sshTarget?.trim() || 'nas',
  };
}

function shellSingleQuote(value: string): string {
  return `'${value.replaceAll("'", "'\"'\"'")}'`;
}

function powerShellSingleQuote(value: string): string {
  return `'${value.replaceAll("'", "''")}'`;
}

function numberOrNull(value: unknown): number | null {
  return typeof value === 'number' && Number.isFinite(value) ? value : null;
}

function stringOrNull(value: unknown): string | null {
  return typeof value === 'string' && value.length > 0 ? value : null;
}

function parseJsonObject(value: string): Record<string, unknown> | null {
  try {
    const parsed = JSON.parse(value);
    return parsed && typeof parsed === 'object'
      ? (parsed as Record<string, unknown>)
      : null;
  } catch {
    return null;
  }
}

function getPath(source: unknown, keys: string[]): unknown {
  return keys.reduce<unknown>((current, key) => {
    if (!current || typeof current !== 'object') return undefined;
    return (current as Record<string, unknown>)[key];
  }, source);
}

function getArray(source: unknown, keys: string[]): unknown[] {
  const value = getPath(source, keys);
  return Array.isArray(value) ? value : [];
}

function buildRemoteScript(input: NormalizedInput): string {
  const smokeBlock = input.smoke
    ? [
        "section smoke_text",
        `${input.smoke} 2>&1 || true`,
      ].join('\n')
    : [
        "section smoke_text",
        "echo 'no task smoke command provided'",
      ].join('\n');

  return [
    'set -u',
    'section() { printf "\\n__KT_SECTION:%s__\\n" "$1"; }',
    `JOB_NAME=${shellSingleQuote(input.jobName)}`,
    `BUILD_NUMBER=${shellSingleQuote(input.buildNumber || '')}`,
    `JENKINS_HOME=${shellSingleQuote(input.jenkinsHome)}`,
    `KUBECONFIG_PATH=${shellSingleQuote(input.kubeconfigPath)}`,
    `NAMESPACE=${shellSingleQuote(input.namespace)}`,
    `DEPLOYMENT=${shellSingleQuote(input.deployment)}`,
    `SELECTOR=${shellSingleQuote(input.selector)}`,
    `HEALTH_URL=${shellSingleQuote(input.healthUrl)}`,
    'JOB_DIR="$JENKINS_HOME/jobs/$JOB_NAME/builds"',
    'if [ -z "$BUILD_NUMBER" ] && [ -d "$JOB_DIR" ]; then BUILD_NUMBER="$(find "$JOB_DIR" -maxdepth 1 -type d -printf "%f\\n" 2>/dev/null | grep -E "^[0-9]+$" | sort -n | tail -1 || true)"; fi',
    'BUILD_DIR="$JOB_DIR/$BUILD_NUMBER"',
    'section jenkins_meta',
    'printf "jobName=%s\\n" "$JOB_NAME"',
    'printf "buildNumber=%s\\n" "$BUILD_NUMBER"',
    'if [ -f "$BUILD_DIR/build.xml" ]; then grep -E "<result>|<number>|<SHA1>" "$BUILD_DIR/build.xml" | tail -20 || true; fi',
    'section jenkins_log_tail',
    'if [ -f "$BUILD_DIR/log" ]; then tail -160 "$BUILD_DIR/log" || true; else echo "jenkins log not found"; fi',
    'section deployment_json',
    'kubectl --kubeconfig "$KUBECONFIG_PATH" -n "$NAMESPACE" get deployment "$DEPLOYMENT" -o json 2>/dev/null || true',
    'section pods_json',
    'kubectl --kubeconfig "$KUBECONFIG_PATH" -n "$NAMESPACE" get pods -l "$SELECTOR" -o json 2>/dev/null || true',
    'section events_tail',
    'kubectl --kubeconfig "$KUBECONFIG_PATH" -n "$NAMESPACE" get events --sort-by=.lastTimestamp 2>/dev/null | tail -80 || true',
    'section health_json',
    'curl -fsS --max-time 8 "$HEALTH_URL" 2>/dev/null || true',
    smokeBlock,
  ].join('\n');
}

function buildPowerShellCommand(input: NormalizedInput): string {
  const remoteScript = buildRemoteScript(input);
  return [
    `$remoteScript = @'`,
    remoteScript,
    `'@`,
    `$remoteScript | ssh -p ${input.sshPort} ${input.sshTarget} "tr -d '\\015' | bash -s"`,
  ].join('\n');
}

export function buildDeployObservationCommands(
  input: DeployObservationInput = {},
): DeployObservationCommand[] {
  const normalized = normalizeInput(input);
  return [
    {
      command: buildPowerShellCommand(normalized),
      name: 'nas-deploy-observation',
    },
  ];
}

export function buildDeployObservationSectionMap(stdout: string): Map<string, string> {
  const sections = new Map<string, string>();
  let currentName: string | null = null;
  let currentLines: string[] = [];

  for (const line of stdout.split(/\r?\n/)) {
    const marker = line.match(/^__KT_SECTION:([a-z0-9_-]+)__$/i);
    if (marker) {
      if (currentName) sections.set(currentName, currentLines.join('\n').trim());
      currentName = marker[1];
      currentLines = [];
    } else if (currentName) {
      currentLines.push(line);
    }
  }

  if (currentName) sections.set(currentName, currentLines.join('\n').trim());
  return sections;
}

function normalizeJenkinsEvidence(
  input: NormalizedInput,
  sectionMap: Map<string, string>,
): DeployObservationJenkinsEvidence {
  const meta = sectionMap.get('jenkins_meta') || '';
  const log = sectionMap.get('jenkins_log_tail') || '';
  const buildNumber =
    input.buildNumber ||
    meta.match(/^buildNumber=(.+)$/m)?.[1]?.trim() ||
    null;
  const finishedStatus =
    log.match(/Finished:\s*([A-Z]+)/)?.[1] ||
    meta.match(/<result>([^<]+)<\/result>/)?.[1] ||
    null;
  const expectedCommit = input.expectedCommit || null;

  return {
    buildNumber,
    commitMatched: expectedCommit
      ? `${meta}\n${log}`.includes(expectedCommit)
      : null,
    expectedCommit,
    finishedStatus,
    jobName: input.jobName,
  };
}

function normalizeDeploymentEvidence(
  input: NormalizedInput,
  sectionMap: Map<string, string>,
): DeployObservationDeploymentEvidence {
  const deployment = parseJsonObject(sectionMap.get('deployment_json') || '');
  const containers = getArray(deployment, [
    'spec',
    'template',
    'spec',
    'containers',
  ]);
  const container = containers.find(
    (item) =>
      item &&
      typeof item === 'object' &&
      (item as Record<string, unknown>).name === input.container,
  ) as Record<string, unknown> | undefined;

  return {
    container: input.container,
    generation: numberOrNull(getPath(deployment, ['metadata', 'generation'])),
    image: stringOrNull(container?.image),
    namespace: input.namespace,
    observedGeneration: numberOrNull(
      getPath(deployment, ['status', 'observedGeneration']),
    ),
    readyReplicas: numberOrNull(getPath(deployment, ['status', 'readyReplicas'])),
    updatedReplicas: numberOrNull(
      getPath(deployment, ['status', 'updatedReplicas']),
    ),
  };
}

function normalizePodEvidence(
  input: NormalizedInput,
  sectionMap: Map<string, string>,
): DeployObservationPodEvidence {
  const pods = parseJsonObject(sectionMap.get('pods_json') || '');
  const items = getArray(pods, ['items']);
  const normalizedPods = items.map((item) => {
    const pod = item as Record<string, unknown>;
    const statuses = getArray(pod, ['status', 'containerStatuses']);
    const status = statuses.find(
      (candidate) =>
        candidate &&
        typeof candidate === 'object' &&
        (candidate as Record<string, unknown>).name === input.container,
    ) as Record<string, unknown> | undefined;
    return {
      image: stringOrNull(status?.image),
      name: stringOrNull(getPath(pod, ['metadata', 'name'])),
      phase: stringOrNull(getPath(pod, ['status', 'phase'])),
      ready: typeof status?.ready === 'boolean' ? status.ready : null,
      restartCount: numberOrNull(status?.restartCount),
    };
  });

  return (
    normalizedPods.find(
      (pod) =>
        pod.phase === 'Running' &&
        (!input.imageTag || pod.image?.includes(input.imageTag)),
    ) ||
    normalizedPods.find((pod) => pod.phase === 'Running') ||
    normalizedPods[0] || {
      image: null,
      name: null,
      phase: null,
      ready: null,
      restartCount: null,
    }
  );
}

function normalizeRuntimeHealthEvidence(
  sectionMap: Map<string, string>,
): DeployObservationRuntimeHealthEvidence {
  const health = parseJsonObject(sectionMap.get('health_json') || '');
  const checks = Array.isArray(health?.checks) ? health.checks : null;

  return {
    checkCount: checks ? checks.length : null,
    service: stringOrNull(health?.service),
    status: stringOrNull(health?.status),
  };
}

function buildAssertion(
  name: string,
  passed: boolean,
  message: string,
  critical = true,
): DeployObservationAssertion {
  return {
    critical,
    message,
    name,
    passed,
  };
}

function aggregateStatus(assertions: DeployObservationAssertion[]): DeployObservationStatus {
  if (assertions.some((item) => item.critical && !item.passed)) return 'failed';
  if (assertions.some((item) => !item.critical && !item.passed)) return 'blocked';
  return 'passed';
}

export function normalizeDeployObservationEvidence({
  checkedAt = new Date(),
  input,
  sectionMap,
}: NormalizeEvidenceInput): DeployObservationEvidence {
  const normalized = normalizeInput(input);
  const jenkins = normalizeJenkinsEvidence(normalized, sectionMap);
  const deployment = normalizeDeploymentEvidence(normalized, sectionMap);
  const pod = normalizePodEvidence(normalized, sectionMap);
  const runtimeHealth = normalizeRuntimeHealthEvidence(sectionMap);
  const smokeOutput = sectionMap.get('smoke_text') || '';
  const assertions = [
    buildAssertion(
      'jenkins-finished',
      jenkins.finishedStatus === 'SUCCESS',
      `Jenkins result is ${jenkins.finishedStatus || 'missing'}`,
    ),
    buildAssertion(
      'jenkins-commit',
      jenkins.commitMatched !== false,
      jenkins.expectedCommit
        ? `Expected commit ${jenkins.expectedCommit} was found in Jenkins evidence`
        : 'No expected commit supplied; commit match skipped',
      Boolean(jenkins.expectedCommit),
    ),
    buildAssertion(
      'deployment-observed-generation',
      deployment.generation !== null &&
        deployment.observedGeneration !== null &&
        deployment.observedGeneration >= deployment.generation,
      `Deployment observedGeneration=${deployment.observedGeneration} generation=${deployment.generation}`,
    ),
    buildAssertion(
      'deployment-ready-replicas',
      deployment.updatedReplicas !== null &&
        deployment.readyReplicas !== null &&
        deployment.desiredReplicas !== null &&
        deployment.updatedReplicas >= deployment.desiredReplicas &&
        deployment.readyReplicas >= deployment.desiredReplicas,
      `Deployment desired=${deployment.desiredReplicas} updated=${deployment.updatedReplicas} ready=${deployment.readyReplicas}`,
    ),
    buildAssertion(
      'pod-running-for-image',
      pod.phase === 'Running' &&
        pod.ready === true &&
        (!normalized.imageTag || Boolean(pod.image?.includes(normalized.imageTag))),
      `Pod ${pod.name || 'missing'} phase=${pod.phase || 'missing'} image=${pod.image || 'missing'}`,
    ),
    buildAssertion(
      'pod-restart-count-zero',
      pod.restartCount === 0,
      `Pod restartCount=${pod.restartCount}`,
    ),
    buildAssertion(
      'runtime-health-not-blocked',
      runtimeHealth.service === 'kt-template-online-api' &&
        runtimeHealth.status !== null &&
        runtimeHealth.status !== 'blocked',
      `Runtime health status=${runtimeHealth.status || 'missing'}`,
    ),
    buildAssertion(
      'task-smoke-present',
      Boolean(normalized.smoke && smokeOutput.trim().length > 0),
      normalized.smoke
        ? 'Task smoke command produced output'
        : 'No task smoke command supplied; rollout evidence is not functional evidence',
      Boolean(normalized.smoke),
    ),
  ];

  return {
    assertions,
    details: {
      deployment,
      eventsTail: sectionMap.get('events_tail') || '',
      jenkins,
      pod,
      runtimeHealth,
      smoke: {
        command: normalized.smoke || null,
        output: smokeOutput,
      },
    },
    endedAt: checkedAt.toISOString(),
    environment: 'production',
    operation: 'kt_deploy_observation',
    project: normalized.project,
    schemaVersion: 1,
    startedAt: checkedAt.toISOString(),
    status: aggregateStatus(assertions),
    target: `${normalized.namespace}/${normalized.deployment}`,
    taskType: 'deploy',
    title: 'KT API deployment observation',
  };
}

function writeEvidenceArtifact(
  artifactRoot: string,
  evidence: DeployObservationEvidence,
): string {
  const root = resolveInsideRoot(artifactRoot);
  const directory = path.join(root, formatDateInShanghai());
  mkdirSync(directory, { recursive: true });
  const filePath = path.join(
    directory,
    `${evidence.project}-${Date.now()}-deploy-observation.json`,
  );
  writeFileSync(filePath, `${JSON.stringify(evidence, null, 2)}\n`, 'utf8');
  return filePath;
}

export async function buildDeployObservation(
  input: DeployObservationInput = {},
): Promise<DeployObservationResult> {
  const normalized = normalizeInput(input);
  const commands = buildDeployObservationCommands(normalized);
  const requiredEvidence = [
    'Jenkins job/build number and final Finished status',
    'Expected commit hash match when a commit is supplied',
    'K8s Deployment generation, observedGeneration, updatedReplicas, readyReplicas',
    'Running Pod selected by current image tag with restartCount',
    'GET /health/runtime response with service/status/check count',
    'Task-specific smoke command output',
  ];
  const notes = [
    'Default execute=false only returns the bounded read-only command.',
    'execute=true runs through ssh nas with CRLF-stripped here-string and writes local JSON evidence.',
    'Jenkins/K8s rollout evidence is deployment evidence; task smoke is still required for functional completion.',
    'The command reads Jenkins build files, kubectl status, events, and HTTP health only; it does not read Secrets or mutate remote state.',
  ];

  if (!normalized.execute) {
    return {
      commands,
      execute: false,
      notes,
      requiredEvidence,
    };
  }

  const command = commands[0]?.command || '';
  const result = await tryPowerShell(command, workspaceRoot, 180_000);
  const sectionMap = buildDeployObservationSectionMap(result.stdout);
  const evidence = normalizeDeployObservationEvidence({
    input: normalized,
    sectionMap,
  });
  const artifactPath = writeEvidenceArtifact(normalized.artifactRoot, evidence);

  return {
    artifactPath,
    commands,
    evidence,
    execute: true,
    notes,
    requiredEvidence,
    result,
  };
}
```

- [ ] **Step 2: Run typecheck and confirm parser/register failures remain**

Run:

```powershell
pnpm --dir D:\MyFiles\KT\mcp\ktWorkflow run typecheck
```

Expected:

```text
FAIL only because parseDeployObservationCliArgs and tool registration are not wired yet.
```

## Task 4: Wire CLI And MCP Registration

**Files:**
- Modify: `D:\MyFiles\KT\mcp\ktWorkflow\src\core\cli.ts`
- Modify: `D:\MyFiles\KT\mcp\ktWorkflow\src\registerTools.ts`
- Modify: `D:\MyFiles\KT\mcp\ktWorkflow\src\server.ts`
- Modify: `D:\MyFiles\KT\mcp\ktWorkflow\src\core\constants.ts`
- Modify: `D:\MyFiles\KT\mcp\ktWorkflow\package.json`

- [ ] **Step 1: Add CLI parser**

Modify the type imports in `src/core/cli.ts`:

```ts
import type {
  DeployObservationInput,
  GlobalCodeReviewInput,
  ObsidianContextInput,
  ObsidianSyncInput,
  ObsidianValidateInput,
  WorkstreamCloseoutInput,
  WorkstreamReusablePattern,
} from '../types.js';
```

Append this parser to `src/core/cli.ts`:

```ts
export function parseDeployObservationCliArgs(argv: string[]): DeployObservationInput {
  const sshPort = Number(readOption(argv, ['--ssh-port', '--sshPort']));

  return {
    artifactRoot: readOption(argv, ['--artifact-root', '--artifactRoot']),
    buildNumber: readOption(argv, ['--build', '--build-number', '--buildNumber']),
    container: readOption(argv, ['--container']),
    deployment: readOption(argv, ['--deployment']),
    execute: argv.includes('--execute'),
    expectedCommit: readOption(argv, ['--commit', '--expected-commit', '--expectedCommit']),
    healthUrl: readOption(argv, ['--health-url', '--healthUrl']),
    imageTag: readOption(argv, ['--image-tag', '--imageTag']),
    jenkinsHome: readOption(argv, ['--jenkins-home', '--jenkinsHome']),
    jobName: readOption(argv, ['--job', '--job-name', '--jobName']),
    kubeconfigPath: readOption(argv, ['--kubeconfig', '--kubeconfig-path', '--kubeconfigPath']),
    namespace: readOption(argv, ['--namespace']),
    project: readOption(argv, ['--project']),
    selector: readOption(argv, ['--selector']),
    smoke: readOption(argv, ['--smoke']),
    sshPort: Number.isFinite(sshPort) ? sshPort : undefined,
    sshTarget: readOption(argv, ['--ssh', '--ssh-target', '--sshTarget']),
  };
}
```

- [ ] **Step 2: Register the MCP tool**

Modify imports in `src/registerTools.ts`:

```ts
import { buildDeployObservation } from './tools/deployObservation.js';
```

Add this registration after `kt_remote_health_check`:

```ts
  server.registerTool(
    'kt_deploy_observation',
    {
      description:
        '生成或执行 API 发布后的只读部署观测：Jenkins、K8s Deployment、Pod、/health/runtime 和任务 smoke，并输出运行态证据。',
      inputSchema: {
        artifactRoot: z.string().optional(),
        buildNumber: z.string().optional(),
        container: z.string().default('api'),
        deployment: z.string().default('kt-template-online-api'),
        execute: z.boolean().default(false),
        expectedCommit: z.string().optional(),
        healthUrl: z.string().default('http://127.0.0.1:48085/health/runtime'),
        imageTag: z.string().optional(),
        jenkinsHome: z.string().default('/vol1/docker/jenkins/jenkins_home'),
        jobName: z.string().default('KT-Template/KT-Template-API/main'),
        kubeconfigPath: z
          .string()
          .default('/vol1/docker/kt-k8s/kubeconfig/kt-nas.jenkins.yaml'),
        namespace: z.string().default('kt-prod'),
        project: z.string().default('api'),
        selector: z.string().default('app=kt-template-online-api'),
        smoke: z.string().optional(),
        sshPort: z.number().int().min(1).max(65_535).default(2202),
        sshTarget: z.string().default('nas'),
      },
      title: 'KT Deploy Observation',
    },
    async (input) => response(await buildDeployObservation(input)),
  );
```

- [ ] **Step 3: Add CLI branch**

Modify imports in `src/server.ts`:

```ts
import {
  parseDeployObservationCliArgs,
  parseGlobalReviewCliArgs,
  parseObsidianContextCliArgs,
  parseObsidianCliArgs,
  parseObsidianSyncCliArgs,
  parseWorkstreamCloseoutCliArgs,
} from './core/cli.js';
import { buildDeployObservation } from './tools/deployObservation.js';
```

Add this branch before `--self-test`:

```ts
} else if (process.argv.includes('--deploy-observation')) {
  console.log(
    JSON.stringify(
      await buildDeployObservation(parseDeployObservationCliArgs(process.argv)),
      null,
      2,
    ),
  );
```

- [ ] **Step 4: Add registered tool name**

Add to `registeredToolNames` in `src/core/constants.ts` immediately after `kt_remote_health_check`:

```ts
  'kt_deploy_observation',
```

- [ ] **Step 5: Add package script**

Add to `scripts` in `package.json`:

```json
"deploy-observation": "node --import ./node_modules/tsx/dist/loader.mjs src/server.ts --deploy-observation"
```

- [ ] **Step 6: Run typecheck and self-test**

Run:

```powershell
pnpm --dir D:\MyFiles\KT\mcp\ktWorkflow run typecheck
pnpm --dir D:\MyFiles\KT\mcp\ktWorkflow run self-test
```

Expected:

```text
typecheck passes.
self-test writes .kt-workspace/test-artifacts/ktWorkflow-self-test.json and exits successfully.
```

- [ ] **Step 7: Commit the tool wiring**

Run:

```powershell
git -C D:\MyFiles\KT\mcp\ktWorkflow add src/tools/deployObservation.ts src/types.ts src/core/cli.ts src/registerTools.ts src/server.ts src/core/constants.ts src/selfTest.ts package.json
git -C D:\MyFiles\KT\mcp\ktWorkflow commit -m "feat: 添加部署观测工作流"
```

Expected:

```text
Commit succeeds on dev and contains only ktWorkflow deploy observation code and tests.
```

## Task 5: Update ktWorkflow Documentation And Closeout Guidance

**Files:**
- Modify: `D:\MyFiles\KT\mcp\ktWorkflow\README.md`
- Modify: `D:\MyFiles\KT\mcp\ktWorkflow\src\tools\closeout.ts`

- [ ] **Step 1: Update closeout deploy-observation target**

In `src/tools/closeout.ts`, change the `deploy-observation` target to:

```ts
  'deploy-observation': {
    files: ['src/tools/deployObservation.ts', 'src/tools/workflow.ts', 'src/tools/testing.ts', 'README.md'],
    label: '部署观测',
    prompt: '把 Jenkins/K8s build、commit、镜像、Deployment、Pod、/health/runtime、日志和 smoke 观测步骤写成固定计划。',
  },
```

- [ ] **Step 2: Update README capability list**

Add this bullet to the capability list in `README.md`:

```markdown
- 生成或执行部署观测：把 Jenkins build、commit、K8s Deployment、Pod、`/health/runtime` 和任务 smoke 汇总成 `.kt-workspace/test-artifacts/deploy-observation` 下的运行态证据。
```

- [ ] **Step 3: Update README tool table**

Add this row after `kt_remote_health_check`:

```markdown
| `kt_deploy_observation`  | 生成或执行 API 发布后的部署观测，汇总 Jenkins、K8s、Pod、`/health/runtime` 和任务 smoke 证据                 |
```

- [ ] **Step 4: Update README scripts table**

Add this row in the script table:

```markdown
| `pnpm run deploy-observation` | 默认 dry-run 输出只读 NAS 观测命令；传 `--execute` 时执行 Jenkins/K8s/health/smoke 观测并写入 `.kt-workspace/test-artifacts/deploy-observation`。 |
```

- [ ] **Step 5: Add README usage guidance**

Add this guidance near the remote health check note:

```markdown
- API 推送触发 Jenkins/K8s 后先运行 `pnpm run deploy-observation -- --project api --job KT-Template/KT-Template-API/main --namespace kt-prod --deployment kt-template-online-api --container api --health-url http://127.0.0.1:48085/health/runtime --smoke "curl -fsS --max-time 8 http://127.0.0.1:48085/health/runtime"` 查看 dry-run 命令；确认需要线上只读观测时再加 `--execute`。Deployment/Pod 成功只算发布证据，功能完成还必须看 smoke 输出。
```

- [ ] **Step 6: Run self-test**

Run:

```powershell
pnpm --dir D:\MyFiles\KT\mcp\ktWorkflow run self-test
```

Expected:

```text
self-test passes after closeout guidance change.
```

- [ ] **Step 7: Commit docs and closeout guidance**

Run:

```powershell
git -C D:\MyFiles\KT\mcp\ktWorkflow add README.md src/tools/closeout.ts
git -C D:\MyFiles\KT\mcp\ktWorkflow commit -m "docs: 补充部署观测工作流说明"
```

Expected:

```text
Commit succeeds on dev with README and closeout guidance only.
```

## Task 6: Validate Dry-Run And Read-Only Observation

**Files:**
- Evidence output: `D:\MyFiles\KT\.kt-workspace\test-artifacts\deploy-observation`

- [ ] **Step 1: Confirm package manager and Node compatibility**

Run:

```powershell
node -v
pnpm -v
Get-Content D:\MyFiles\KT\mcp\ktWorkflow\package.json | Select-String -Pattern '"engines"|"packageManager"'
```

Expected:

```text
Node satisfies >=20.19.0 and pnpm matches or is compatible with pnpm@10.28.2.
```

If Node does not satisfy `engines`, run:

```powershell
nvm ls
nvm use 20.19.0
```

- [ ] **Step 2: Run static validation**

Run:

```powershell
pnpm --dir D:\MyFiles\KT\mcp\ktWorkflow run typecheck
pnpm --dir D:\MyFiles\KT\mcp\ktWorkflow run self-test
```

Expected:

```text
Both commands pass.
```

- [ ] **Step 3: Run deploy observation dry-run**

Run:

```powershell
pnpm --dir D:\MyFiles\KT\mcp\ktWorkflow run deploy-observation -- --project api --job KT-Template/KT-Template-API/main --namespace kt-prod --deployment kt-template-online-api --container api --health-url http://127.0.0.1:48085/health/runtime --smoke "curl -fsS --max-time 8 http://127.0.0.1:48085/health/runtime"
```

Expected:

```text
JSON output has execute=false, a nas-deploy-observation command, requiredEvidence, and notes.
No SSH command is executed.
No artifact is written.
```

- [ ] **Step 4: Run read-only online observation**

Run only after confirming NAS SSH is expected to be reachable:

```powershell
pnpm --dir D:\MyFiles\KT\mcp\ktWorkflow run deploy-observation -- --execute --project api --job KT-Template/KT-Template-API/main --namespace kt-prod --deployment kt-template-online-api --container api --health-url http://127.0.0.1:48085/health/runtime --smoke "curl -fsS --max-time 8 http://127.0.0.1:48085/health/runtime"
```

Expected:

```text
JSON output includes execute=true, result.ok, evidence, and artifactPath.
artifactPath is under D:\MyFiles\KT\.kt-workspace\test-artifacts\deploy-observation.
Evidence contains Jenkins, Deployment, Pod, runtimeHealth, smoke, and assertions.
If Jenkins/K8s/health is unavailable, the evidence status is failed with concrete failing assertions.
```

- [ ] **Step 5: Inspect artifact without leaking noisy payloads**

Run:

```powershell
Get-ChildItem D:\MyFiles\KT\.kt-workspace\test-artifacts\deploy-observation -Recurse -Filter *deploy-observation.json | Sort-Object LastWriteTime -Descending | Select-Object -First 1 | ForEach-Object { Get-Content $_.FullName | ConvertFrom-Json | Select-Object title,status,target,operation,project }
```

Expected:

```text
The latest artifact summary shows operation=kt_deploy_observation and a concrete status.
```

## Task 7: Documentation Sync, Cleanup, Review, And Commits

**Files:**
- Modify: `D:\MyFiles\KT\TASKS.md`

- [ ] **Step 1: Run doc sync plan**

MCP call:

```json
{
  "changedFiles": [
    "mcp/ktWorkflow/src/tools/deployObservation.ts",
    "mcp/ktWorkflow/src/types.ts",
    "mcp/ktWorkflow/src/core/cli.ts",
    "mcp/ktWorkflow/src/registerTools.ts",
    "mcp/ktWorkflow/src/server.ts",
    "mcp/ktWorkflow/src/core/constants.ts",
    "mcp/ktWorkflow/src/selfTest.ts",
    "mcp/ktWorkflow/src/tools/closeout.ts",
    "mcp/ktWorkflow/README.md",
    "mcp/ktWorkflow/package.json"
  ],
  "project": "mcp",
  "taskType": "mcp"
}
```

Expected:

```text
Doc sync identifies README and KT workflow documentation as handled; no API contract doc change is required because /health/runtime contract did not change.
```

If the MCP tool is unavailable in the execution environment, inspect `mcp/ktWorkflow/README.md`, `Node/kt-template-online-api/README.md`, `Node/kt-template-online-api/API.md`, and `docs/obsidian/modules/KT 模块 - API Backend.md` manually, then record the manual doc sync result in closeout evidence.

- [ ] **Step 2: Update TASKS.md**

Add a recent record with this content shape:

```markdown
### 2026-06-14：API Runtime Foundation Phase 2 部署观测

- 范围：mcp/ktWorkflow、Node/kt-template-online-api docs
- 关键词：API Runtime Foundation、DeployObservationAdapter、Jenkins、K8s、/health/runtime、ktWorkflow
- 验证：pnpm --dir mcp/ktWorkflow run typecheck；pnpm --dir mcp/ktWorkflow run self-test；deploy-observation dry-run；deploy-observation --execute 只读观测或明确记录 NAS 不可达阻塞。
```

- [ ] **Step 3: Run cleanup preview**

Run:

```powershell
pnpm --dir D:\MyFiles\KT\mcp\ktWorkflow run cleanup-history -- --dry-run
```

Expected:

```text
Output lists deleted=[] or a finite set of stale .kt-workspace artifacts.
```

If stale artifacts are listed, run:

```powershell
pnpm --dir D:\MyFiles\KT\mcp\ktWorkflow run cleanup-history -- --execute
pnpm --dir D:\MyFiles\KT\mcp\ktWorkflow run cleanup-history -- --dry-run
```

Expected:

```text
Final dry-run shows deleted=[].
```

- [ ] **Step 4: Run KT global review**

Run:

```powershell
pnpm --dir D:\MyFiles\KT\mcp\ktWorkflow run global-review
```

Expected:

```text
No Critical or Important findings caused by this change.
Known pre-existing dirty files are classified separately.
```

- [ ] **Step 5: Request KT global review**

Use `KT global review` after implementation and before declaring the work complete. Review must cover:

```text
mcp/ktWorkflow deploy observation command safety
evidence normalization correctness
Jenkins/K8s success not being treated as functional smoke success
dirty ktWorkflow files preserved rather than overwritten
```

Expected:

```text
All Critical and Important findings are fixed or explicitly rejected with evidence before finishing.
```

- [ ] **Step 6: Run closeout audit**

Run:

```powershell
pnpm --dir D:\MyFiles\KT\mcp\ktWorkflow run workstream-closeout -- --title "API Runtime Foundation Phase 2 部署观测" --project mcp --project api --verification "typecheck/self-test/deploy-observation dry-run/read-only observation evidence" --doc-sync "kt_change_doc_sync README handled; API health contract unchanged" --cleanup "cleanup-history final dry-run deleted=[]" --cleanup-final-deleted 0 --review "global-review no Critical/Important findings caused by this change" --problem "无新卡点或已记录 NAS/Jenkins/K8s 只读观测阻塞" --solution "kt_deploy_observation 固化 Jenkins/K8s/health/smoke 观测" --pattern deploy-observation --kt-workflow-updated --upgrade-notes "新增 kt_deploy_observation 工具和 CLI"
```

Expected:

```text
canReportComplete=true.
```

- [ ] **Step 7: Commit root TASKS update if changed**

Run:

```powershell
git -C D:\MyFiles\KT status --short -- TASKS.md
git -C D:\MyFiles\KT add TASKS.md
git -C D:\MyFiles\KT commit -m "docs: 记录API部署观测重构进度"
```

Expected:

```text
Root commit contains only the task record update made for this phase.
```

## Self-Review

- Spec coverage:
  - Jenkins job/build number is covered by `jenkins_meta` and `jenkins_log_tail`.
  - Commit hash is covered by `expectedCommit` and `jenkins-commit` assertion.
  - Image tag is covered by Deployment container image and Pod image match.
  - Deployment `generation`, `observedGeneration`, `updatedReplicas`, and `readyReplicas` are parsed from `deployment_json`.
  - Running Pod and restart count are parsed from `pods_json`.
  - Failing logs/events are included through `jenkins_log_tail` and `events_tail`.
  - `/health/runtime` is fetched as `health_json` and normalized without exposing config topology.
  - Task-specific smoke is separate from rollout evidence through `task-smoke-present`.

- Placeholder scan:
  - This plan contains concrete file paths, code snippets, commands, expected outputs, and commit messages.
  - No step asks the implementer to invent a missing function name or validation command.

- Type consistency:
  - `parseDeployObservationCliArgs`, `buildDeployObservation`, `buildDeployObservationSectionMap`, and `normalizeDeployObservationEvidence` are introduced in early tasks and referenced consistently in later tasks.
  - `DeployObservationInput`, `DeployObservationEvidence`, and `DeployObservationResult` live in `src/types.ts` and are consumed by the new tool and registration.