@zaip-ai/cli 1.0.4 → 1.0.7

package/templates/.agents/skills/zaip-skill-reconcile-telemetry/scripts/reconcile-telemetry-remeasurement.mjs

@@ -0,0 +1,167 @@
+import { appendFile, open, readFile, rm } from "node:fs/promises";
+import {
+  aggregate,
+  exactRemeasurementSegment,
+  jsonLines,
+  pricingFor,
+  recordPhase,
+  recordSequence,
+  recordType,
+  usageStatus,
+  usageView,
+} from "./reconcile-telemetry-lib.mjs";
+
+export const remeasureSelectedRuns = async ({
+  apply,
+  allSegments,
+  runs,
+  selectedRunIds,
+  timingOnly = false,
+  workspace,
+}) => {
+  const remeasurement = [];
+  for (const runId of selectedRunIds) {
+    const run = runs.find((candidate) => candidate.started.run_id === runId);
+    if (!run) {
+      remeasurement.push({ run_id: runId, eligible: false, reason: "run-not-found" });
+      continue;
+    }
+    const effective = usageStatus(run.usage).effective.filter(
+      (usage) => usage.tokens?.input !== null && usage.tokens?.output !== null,
+    );
+    const superseded = effective.at(-1) ?? null;
+    const finished = run.records.find((record) => recordType(record) === "run.finished");
+    const match = exactRemeasurementSegment(
+      run.started,
+      superseded?.source_segment_key,
+      allSegments,
+    );
+    const segment = match.segment;
+    const ambiguous = match.ambiguous;
+    if (!finished || segment === null || ambiguous || superseded === null) {
+      remeasurement.push({
+        run_id: runId,
+        eligible: false,
+        reason: !finished
+          ? "run-not-finished"
+          : ambiguous
+            ? "ambiguous-segment"
+            : segment === null
+              ? "exact-segment-not-found"
+              : "measured-usage-not-found",
+      });
+      continue;
+    }
+    const tokens = aggregate(segment);
+    const unchanged =
+      superseded.tokens.input === tokens.input &&
+      superseded.tokens.cached_input === tokens.cached_input &&
+      superseded.tokens.output === tokens.output &&
+      superseded.tokens.reasoning === tokens.reasoning &&
+      superseded.tokens.total === tokens.total;
+    const timingChanged =
+      superseded.source_started_at !== segment.started_at ||
+      superseded.source_finished_at !== segment.finished_at;
+    const timingOnlyEligible = timingChanged;
+    const item = {
+      run_id: runId,
+      eligible: !timingOnly || timingOnlyEligible,
+      applied: false,
+      previous_total: superseded.tokens.total,
+      remeasured_total: tokens.total,
+      segment_key: segment.key,
+      supersedes_event_id: superseded.event_id,
+      unchanged,
+      timing_enrichment: timingChanged,
+      ...(timingOnly && !timingOnlyEligible ? { reason: "source-timing-already-complete" } : {}),
+    };
+    remeasurement.push(item);
+    if (!item.eligible || !apply || (unchanged && !timingChanged)) {
+      continue;
+    }
+    const model = segment.model ?? run.started.model ?? null;
+    const recordedTokens = timingOnly
+      ? superseded.tokens
+      : { ...tokens, source: "provider_reported" };
+    const recordedCost = timingOnly ? superseded.cost : await pricingFor(workspace, model, tokens);
+    const sequence = run.records.length + 1;
+    const event = {
+      schema_version: 2,
+      event_id: `${runId}:remeasure:${String(sequence).padStart(6, "0")}`,
+      run_id: runId,
+      sequence,
+      occurred_at: retrospectiveCorrectionOccurredAt(),
+      type: "usage.recorded",
+      phase: recordPhase(finished),
+      activity_kind: "retrospective_local_remeasurement",
+      classification_source: "current_context",
+      tokens: recordedTokens,
+      cost: recordedCost,
+      provider: timingOnly ? superseded.provider : (run.started.provider ?? "openai"),
+      model: timingOnly ? superseded.model : model,
+      source_segment_key: segment.key,
+      supersedes_event_id: superseded.event_id,
+      retrospective_correction: true,
+      source_occurred_at: segment.finished_at ?? segment.started_at,
+      source_started_at: segment.started_at,
+      source_finished_at: segment.finished_at,
+      runtime: {
+        reasoning_effort: timingOnly
+          ? (superseded.runtime?.reasoning_effort ?? null)
+          : segment.effort,
+        service_tier: timingOnly
+          ? (superseded.runtime?.service_tier ?? null)
+          : segment.service_tier,
+      },
+    };
+    await appendRetrospectiveUsage(run.file, run.records, event);
+    item.applied = true;
+    item.write_mode = "history-preserving append under exclusive lock";
+  }
+  return remeasurement;
+};
+
+export async function appendRetrospectiveUsage(file, expectedRecords, event) {
+  assertRetrospectiveAppend(expectedRecords, event);
+  const lockPath = `${file}.lock`;
+  const handle = await open(lockPath, "wx");
+  await handle.close();
+  try {
+    const persisted = jsonLines(await readFile(file, "utf8"));
+    const expectedLast = expectedRecords.at(-1);
+    const persistedLast = persisted.at(-1);
+    if (
+      persisted.length !== expectedRecords.length ||
+      recordSequence(persistedLast) !== recordSequence(expectedLast) ||
+      recordType(persistedLast) !== "run.finished"
+    ) {
+      throw new Error("Run history changed before retrospective append");
+    }
+    assertRetrospectiveAppend(persisted, event);
+    await appendFile(file, `${JSON.stringify(event)}\n`, "utf8");
+  } finally {
+    await rm(lockPath, { force: true });
+  }
+}
+
+export function assertRetrospectiveAppend(records, event) {
+  const finished = records.at(-1);
+  const target = records.find(
+    (record) => usageView(record)?.event_id === event.supersedes_event_id,
+  );
+  if (
+    recordType(finished) !== "run.finished" ||
+    event.type !== "usage.recorded" ||
+    event.retrospective_correction !== true ||
+    event.activity_kind !== "retrospective_local_remeasurement" ||
+    event.phase !== recordPhase(finished) ||
+    recordSequence(event) !== records.length + 1 ||
+    target === undefined
+  ) {
+    throw new Error("Invalid retrospective post-terminal usage correction");
+  }
+}
+
+export function retrospectiveCorrectionOccurredAt(now = () => new Date()) {
+  return now().toISOString();
+}

package/templates/.agents/skills/zaip-skill-reconcile-telemetry/scripts/reconcile-telemetry-remeasurement.test.mjs

@@ -0,0 +1,267 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { after, test } from "node:test";
+import { jsonLines, usageStatus, usageView } from "./reconcile-telemetry-lib.mjs";
+import {
+  appendRetrospectiveUsage,
+  assertRetrospectiveAppend,
+  remeasureSelectedRuns,
+  retrospectiveCorrectionOccurredAt,
+} from "./reconcile-telemetry-remeasurement.mjs";
+
+const roots = [];
+after(async () => Promise.all(roots.map((root) => rm(root, { recursive: true, force: true }))));
+
+test("appends under an exclusive lock without rewriting the terminal history", async () => {
+  const root = await mkdtemp(join(tmpdir(), "zaip-remeasure-append-"));
+  roots.push(root);
+  const file = join(root, "RUN.jsonl");
+  const records = [
+    { type: "run.started", event_id: "RUN:1", sequence: 1, phase: "execution" },
+    { type: "usage.recorded", event_id: "RUN:2", sequence: 2, phase: "execution" },
+    { type: "run.finished", event_id: "RUN:3", sequence: 3, phase: "execution" },
+  ];
+  const original = `${records.map((record) => JSON.stringify(record)).join("\n")}\n`;
+  await writeFile(file, original, "utf8");
+  const correction = {
+    type: "usage.recorded",
+    event_id: "RUN:4",
+    sequence: 4,
+    phase: "execution",
+    activity_kind: "retrospective_local_remeasurement",
+    supersedes_event_id: "RUN:2",
+    retrospective_correction: true,
+  };
+
+  await appendRetrospectiveUsage(file, records, correction);
+
+  const persisted = await readFile(file, "utf8");
+  assert.ok(persisted.startsWith(original));
+  assert.equal(persisted, `${original}${JSON.stringify(correction)}\n`);
+});
+
+test("an unavailable lock leaves the original history byte-identical", async () => {
+  const root = await mkdtemp(join(tmpdir(), "zaip-remeasure-lock-"));
+  roots.push(root);
+  const file = join(root, "RUN.jsonl");
+  const original = [
+    '{"type":"run.started","event_id":"RUN:1","sequence":1,"phase":"execution"}',
+    '{"type":"usage.recorded","event_id":"RUN:2","sequence":2,"phase":"execution"}',
+    '{"type":"run.finished","event_id":"RUN:3","sequence":3,"phase":"execution"}',
+    "",
+  ].join("\n");
+  await writeFile(file, original, "utf8");
+  await writeFile(`${file}.lock`, "held", "utf8");
+
+  await assert.rejects(
+    appendRetrospectiveUsage(file, jsonLines(original), {
+      type: "usage.recorded",
+      event_id: "RUN:4",
+      sequence: 4,
+      phase: "execution",
+      activity_kind: "retrospective_local_remeasurement",
+      supersedes_event_id: "RUN:2",
+      retrospective_correction: true,
+    }),
+    (error) => error?.code === "EEXIST",
+  );
+  assert.equal(await readFile(file, "utf8"), original);
+});
+
+test("uses run.finished phase after planning transitions to execution and rereads effective usage", async () => {
+  const root = await mkdtemp(join(tmpdir(), "zaip-remeasure-phase-"));
+  roots.push(root);
+  await mkdir(join(root, ".agents", "config", "pricing"), { recursive: true });
+  await writeFile(
+    join(root, ".agents", "config", "pricing", "models.json"),
+    JSON.stringify({
+      models: [
+        {
+          id: "gpt-test",
+          aliases: [],
+          input_per_million_usd: 1,
+          cached_input_per_million_usd: 1,
+          output_per_million_usd: 1,
+          reasoning_per_million_usd: 1,
+          long_context_threshold_tokens: null,
+        },
+      ],
+    }),
+  );
+  const file = join(root, "RUN-PHASE.jsonl");
+  const records = [
+    {
+      type: "run.started",
+      event_id: "RUN-PHASE:1",
+      run_id: "RUN-PHASE",
+      sequence: 1,
+      phase: "planning",
+    },
+    {
+      type: "usage.recorded",
+      event_id: "RUN-PHASE:2",
+      run_id: "RUN-PHASE",
+      sequence: 2,
+      phase: "execution",
+      activity_kind: "implementation",
+      tokens: { input: 10, cached_input: 0, output: 2, reasoning: 0, total: 12 },
+      supersedes_event_id: null,
+      source_segment_key: "session#1",
+      model: "gpt-test",
+    },
+    [3, "f", "RUN-PHASE:3", 3, "2026-07-25T04:02:00.000Z", "execution", "completed"],
+  ];
+  await writeFile(file, `${records.map((record) => JSON.stringify(record)).join("\n")}\n`);
+  const run = {
+    file,
+    records,
+    started: {
+      run_id: "RUN-PHASE",
+      phase: "planning",
+      client_turn_id: "turn-phase",
+      model: "gpt-test",
+      provider: "openai",
+    },
+    usage: records.map(usageView).filter(Boolean),
+  };
+  const segment = {
+    key: "session#1",
+    turn_id: "turn-phase",
+    model: "gpt-test",
+    started_at: "2026-07-25T04:00:00.000Z",
+    finished_at: "2026-07-25T04:01:00.000Z",
+    usage: [
+      {
+        input_tokens: 8,
+        cached_input_tokens: 0,
+        output_tokens: 1,
+        reasoning_output_tokens: 0,
+        total_tokens: 9,
+      },
+    ],
+  };
+
+  const [result] = await remeasureSelectedRuns({
+    apply: true,
+    allSegments: [segment],
+    runs: [run],
+    selectedRunIds: new Set(["RUN-PHASE"]),
+    workspace: root,
+  });
+  const persisted = jsonLines(await readFile(file, "utf8"));
+  const correction = usageView(persisted.at(-1));
+  assert.equal(result.applied, true);
+  assert.equal(correction.phase, "execution");
+  assert.equal(usageStatus([...run.usage, correction]).effective.at(-1).tokens.total, 9);
+  assert.throws(
+    () => assertRetrospectiveAppend(records, { ...persisted.at(-1), phase: "planning" }),
+    /Invalid retrospective/,
+  );
+});
+
+test("enriches exact source timing without changing canonical tokens when remeasurement drifts", async () => {
+  const root = await mkdtemp(join(tmpdir(), "zaip-remeasure-timing-"));
+  roots.push(root);
+  await mkdir(join(root, ".agents", "config", "pricing"), { recursive: true });
+  await writeFile(
+    join(root, ".agents", "config", "pricing", "models.json"),
+    JSON.stringify({
+      models: [
+        {
+          id: "gpt-test",
+          aliases: [],
+          input_per_million_usd: 1,
+          cached_input_per_million_usd: 1,
+          output_per_million_usd: 1,
+          reasoning_per_million_usd: 1,
+          long_context_threshold_tokens: null,
+        },
+      ],
+    }),
+  );
+  const file = join(root, "RUN-TIMING.jsonl");
+  const records = [
+    {
+      type: "run.started",
+      event_id: "RUN-TIMING:1",
+      run_id: "RUN-TIMING",
+      sequence: 1,
+      phase: "execution",
+    },
+    {
+      type: "usage.recorded",
+      event_id: "RUN-TIMING:2",
+      run_id: "RUN-TIMING",
+      sequence: 2,
+      phase: "execution",
+      activity_kind: "retrospective_local_reconciliation",
+      tokens: { input: 10, cached_input: 0, output: 2, reasoning: 0, total: 12 },
+      supersedes_event_id: null,
+      source_segment_key: "session#timing",
+      source_occurred_at: "2026-07-25T04:01:00.000Z",
+      model: "gpt-test",
+    },
+    {
+      type: "run.finished",
+      event_id: "RUN-TIMING:3",
+      run_id: "RUN-TIMING",
+      sequence: 3,
+      phase: "execution",
+    },
+  ];
+  await writeFile(file, `${records.map((record) => JSON.stringify(record)).join("\n")}\n`);
+  const run = {
+    file,
+    records,
+    started: {
+      run_id: "RUN-TIMING",
+      phase: "execution",
+      client_turn_id: "turn-timing",
+      model: "gpt-test",
+      provider: "openai",
+    },
+    usage: records.map(usageView).filter(Boolean),
+  };
+  const segment = {
+    key: "session#timing",
+    turn_id: "turn-timing",
+    model: "gpt-test",
+    started_at: "2026-07-25T04:00:00.000Z",
+    finished_at: "2026-07-25T04:01:00.000Z",
+    usage: [
+      {
+        input_tokens: 20,
+        cached_input_tokens: 0,
+        output_tokens: 4,
+        reasoning_output_tokens: 0,
+        total_tokens: 24,
+      },
+    ],
+  };
+
+  const [result] = await remeasureSelectedRuns({
+    apply: true,
+    allSegments: [segment],
+    runs: [run],
+    selectedRunIds: new Set(["RUN-TIMING"]),
+    timingOnly: true,
+    workspace: root,
+  });
+  const correction = usageView(jsonLines(await readFile(file, "utf8")).at(-1));
+  assert.equal(result.unchanged, false);
+  assert.equal(result.timing_enrichment, true);
+  assert.equal(result.applied, true);
+  assert.equal(correction.tokens.total, 12);
+  assert.equal(correction.source_started_at, segment.started_at);
+  assert.equal(correction.source_finished_at, segment.finished_at);
+});
+
+test("uses the current correction clock instead of fabricating a pre-finish timestamp", () => {
+  const current = new Date("2026-07-25T04:06:14.352Z");
+  assert.equal(
+    retrospectiveCorrectionOccurredAt(() => current),
+    "2026-07-25T04:06:14.352Z",
+  );
+});

package/templates/.agents/skills/zaip-skill-refactor-existing-code/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: zaip-skill-refactor-existing-code
+description: Analyze, plan, and execute the safe refactor or migration of an existing code folder into the repository's current stack and layout. Use for legacy folders, monolith decomposition, language or framework changes, file relocation, modularization, or UI migration that must classify code as reuse, move, split, adapt, rewrite, or exclude while preserving traceability, visual intent, rollback, and validation gates.
+---
+
+# Refactor Existing Code
+
+1. Read the active ZAIP Rules, Requirements, `.agents/config/project.yaml`, and target architecture before changing code. Compose with [`$zaip-skill-adapt-stack`](../zaip-skill-adapt-stack/SKILL.md) when the source or target stack is unsupported, and [`$zaip-skill-enforce-architecture`](../zaip-skill-enforce-architecture/SKILL.md) when defining or validating boundaries. For UI, read the active `DESIGN.md`.
+2. Route lifecycle without duplicating it: use Task-first for a bounded refactor, a standalone SPEC by default for a folder-wide or structural migration, and a PRD only when product outcomes justify one. Analysis alone remains Conversation; execution requires explicit authority and delegates lifecycle mechanics to the existing Task/SPEC/PRD and execution skills.
+3. Establish a baseline before choosing destinations: public contracts, entrypoints, tests and known failures, observable behavior, visual states, data/storage effects, and rollback constraints. Separate generated, vendor, cache, binary, and secret-bearing material from product code.
+4. Inventory metadata before reading full files. Run `node .agents/skills/zaip-skill-refactor-existing-code/scripts/inventory-source.mjs <source-dir> --output inventory.json`; it writes deterministic UTF-8 JSON atomically and still emits the same JSON to stdout. To inspect a default-ignored root that contains product code, add `--include name[,name...]`. Keep detailed inventory temporary unless audit evidence requires it; persist only a compact, secret-safe decision map. Treat each skipped dependency/build directory emitted as an `ignored-directory` unit that still requires an explicit `exclude` decision.
+5. Assign exactly one action to every inventory unit: `reuse`, `move`, `split`, `adapt`, `rewrite`, or `exclude`. Prefer `reuse` and hash-preserving `move`; require a reason for `rewrite` and `exclude`. Never classify only by file extension or language, and never assume a default-ignored directory contains no product code.
+6. Write a map conforming to [the refactor-map contract](references/refactor-map-contract.md), including origin, destination(s), rationale, dependencies, owning Task, slice, gates, and rollback. Run `node .agents/skills/zaip-skill-refactor-existing-code/scripts/validate-refactor-map.mjs refactor-map.json` before implementation.
+7. Derive the Task DAG from cohesive capabilities and map dependencies, not one Task per file. Order contracts and foundations before adapters and consumers; parallelize only independently testable slices with non-overlapping write scopes.
+8. Assign `preserve`, `conform`, or `hybrid` to every UI unit and apply [the visual-mode contract](references/visual-modes.md). Do not silently mix legacy styling with the active design system or treat source inspection as rendered visual evidence.
+9. Execute one reversible slice at a time: refresh the inventory and compare hashes for touched units, create the target boundary, move or adapt code, migrate consumers, run focused gates, cut over, and only then delete the old path. Invalidate and revise the map when a source hash changes. Keep a compatibility seam, flag, retained route, or revertible commit until cutover passes.
+10. Validate focused behavior after each slice and run applicable target gates at integration: tests, typecheck, build, architecture, modules, profile, CQRS, source-size, security, and rendered UI/accessibility. Execute full-suite gates when risk or the parent lifecycle requires them.
+11. Block completion when inventory coverage is incomplete, a dependency or case-insensitive path collision remains, a public contract changed without a Decision, a required gate ran against another candidate, rollback is unavailable, or the old path still has consumers. Report exclusions, deferrals, baseline failures, and remaining risk explicitly.
+
+## Map shape
+
+Use the inventory output in `inventory.units` and a `units` decision for every path. `destination` may be a string or `destinations` an array; `split` requires two or more destinations. See `references/refactor-map-contract.md` for the schema and decision record.
+
+```json
+{
+  "schema_version": 1,
+  "source_root": "legacy",
+  "target_root": ".",
+  "inventory": {
+    "policy": {
+      "default_ignored_names": [".git", ".next", ".turbo", "build", "coverage", "dist", "node_modules", "out", "target", "vendor"],
+      "included_names": []
+    },
+    "ignored": [],
+    "units": [{
+      "path": "ui/card.tsx",
+      "kind": "file",
+      "sha256": "0000000000000000000000000000000000000000000000000000000000000000"
+    }]
+  },
+  "units": [{
+    "source": "ui/card.tsx",
+    "action": "adapt",
+    "destination": "apps/frontend/src/features/cards/card.tsx",
+    "ui": true,
+    "visual_mode": "hybrid",
+    "depends_on": [],
+    "owner_task": "TASK-EXAMPLE-0001",
+    "slice": "cards-ui",
+    "gates": ["unit", "architecture", "visual"],
+    "rollback": "Restore the legacy import through the compatibility export.",
+    "rationale": "Keep behavior while adopting shared primitives."
+  }]
+}
+```

package/templates/.agents/skills/zaip-skill-refactor-existing-code/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Refactor Existing Code"
+  short_description: "Map and execute safe refactors"
+  default_prompt: "Use $zaip-skill-refactor-existing-code to refactor this folder with a complete map, lifecycle-safe plan, and validation gates."

package/templates/.agents/skills/zaip-skill-refactor-existing-code/references/refactor-map-contract.md

@@ -0,0 +1,33 @@
+# Refactor-map contract
+
+Use `schema_version: 1`, safe relative `source_root` and `target_root`, `inventory.units`, and `units`. Permit `.` for either root. Treat unit paths as portable, root-relative `/` paths; reject absolute paths, drive prefixes, UNC paths, `..`, alternate data streams, Windows reserved names, trailing dots/spaces, duplicates, and case-insensitive collisions.
+
+The inventory comes from `inventory-source.mjs`. Copy its `policy`, `ignored`, and `units` without dropping `path`, `kind`, or file `sha256`; every inventory path requires exactly one decision with the same `source`. The validator requires the canonical default-ignore policy and an explicit list of reviewed `included_names`. The inventory represents skipped dependency/build roots as `kind: "ignored-directory"` instead of traversing them. Require an explicit `exclude` decision for each one; rerun inventory with `--include name[,name...]` when a default-ignored root contains product code.
+
+Treat symbolic links as security boundaries rather than ordinary files. Require `exclude` in the automatic map, then inventory the resolved, authorized target separately if it belongs in scope.
+
+Require these fields for every decision:
+
+- `source`: one inventory path.
+- `action`: `reuse`, `move`, `split`, `adapt`, `rewrite`, or `exclude`.
+- `rationale`: concise reason grounded in stack, contract, behavior, or architecture.
+- `owner_task`: the owning `TASK-*`.
+- `slice`: cohesive cutover unit shared by related decisions.
+- `ui`: explicit boolean declaring UI responsibility.
+- `depends_on`: unique source paths that must complete first.
+- `gates`: non-empty, unique validation names.
+
+Forbid using `destination` and `destinations` together. Require one `destination` for `reuse`, `move`, `adapt`, and `rewrite`; require two or more unique `destinations` for `split`; forbid destinations for `exclude`. Require `rollback` for `move`, `split`, `adapt`, and `rewrite`. Require a valid `visual_mode` (`preserve`, `conform`, or `hybrid`) when `ui: true`; forbid it when `ui: false`.
+
+Interpret actions narrowly:
+
+- `reuse`: retain compatible behavior and boundary at the mapped target.
+- `move`: relocate without intended semantic change; compare source and target hashes.
+- `split`: separate responsibilities while preserving acceptance coverage.
+- `adapt`: preserve purpose while changing a boundary, interface, or framework integration.
+- `rewrite`: replace only after equivalent acceptance coverage proves adaptation unsuitable.
+- `exclude`: omit intentionally with a reviewable reason.
+
+Keep dependencies acyclic and destinations unique across the entire map. A destination cannot also be an ancestor or descendant of another mapped file. Validate collisions case-insensitively for Windows portability.
+
+Treat the map as a planning/evidence attachment, not a new lifecycle entity. Link its compact form to the current Task/SPEC/PRD and Change; do not persist secrets, personal absolute paths, source bodies, or raw context.

package/templates/.agents/skills/zaip-skill-refactor-existing-code/references/visual-modes.md

@@ -0,0 +1,17 @@
+# Visual refactor modes
+
+Choose one mode per UI unit and record the baseline, expected change, routes/states, viewport coverage, accessibility assertions, and rendered validation gate.
+
+## Preserve
+
+Keep approved layout, interaction, copy, assets, responsive behavior, accessibility behavior, and visual baseline. Permit only structural changes required by relocation or modularization. Treat any visible delta as a failed gate unless explicitly accepted.
+
+## Conform
+
+Adopt the active `DESIGN.md`, tokens, components, responsive rules, interaction conventions, and accessibility contract. Record the intended visible changes before implementation; compare the rendered result with design-system specimens and acceptance states.
+
+## Hybrid
+
+Name exactly which product-specific composition and behavior remain and which shared primitives, tokens, or components change. Do not use `hybrid` as an unspecified compromise.
+
+For every mode, verify loading, empty, error, disabled, focus, keyboard, screen-reader, reduced-motion, and relevant responsive states. Validate the actually served UI; source, build, DOM snapshot, or token parity alone is not final visual evidence.