@tryinget/pi-agent-registry 0.3.0

package/src/fleet-git-snapshot.ts

@@ -0,0 +1,323 @@
+// ---
+// summary: captures bounded immutable Git objects plus separate worktree-currentness observations for fleet lint.
+// read_when:
+//   - changing immutable fleet revisions, committed file capture, dirty-state handling, or Git race detection.
+// ---
+
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { realpath } from "node:fs/promises";
+import { isAbsolute, join, relative, resolve } from "node:path";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+const GIT_TIMEOUT_MS = 15_000;
+const MAX_GIT_OUTPUT_BYTES = 8 * 1024 * 1024;
+const FULL_GIT_OID = /^[0-9a-f]{40,64}$/u;
+
+export interface CapturedGitFile {
+  path: string;
+  mode: string;
+  blobOid: string;
+  bytes: Buffer;
+  sha256: string;
+}
+
+export interface FleetGitSnapshot {
+  root: string;
+  commit: string;
+  treeOid: string;
+  status: "clean_observed" | "dirty";
+  statusSha256: string;
+  latestActivityAt?: string;
+  readFile(path: string, maxBytes?: number): Promise<CapturedGitFile | undefined>;
+  finish(): Promise<{ stable: boolean; finalCommit: string; finalStatusSha256: string }>;
+}
+
+export class FleetGitSnapshotError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "FleetGitSnapshotError";
+  }
+}
+
+async function runGit(
+  root: string,
+  args: string[],
+  encoding?: BufferEncoding,
+): Promise<string | Buffer> {
+  try {
+    const result = await execFileAsync(
+      "git",
+      [
+        "--no-pager",
+        "-c",
+        "core.fsmonitor=false",
+        "-c",
+        "core.hooksPath=/dev/null",
+        "-c",
+        "core.untrackedCache=false",
+        "-c",
+        "diff.external=",
+        "-C",
+        root,
+        ...args,
+      ],
+      {
+        encoding: encoding ?? "buffer",
+        timeout: GIT_TIMEOUT_MS,
+        maxBuffer: MAX_GIT_OUTPUT_BYTES,
+        windowsHide: true,
+        env: {
+          PATH: process.env.PATH,
+          LC_ALL: "C",
+          GIT_CONFIG_NOSYSTEM: "1",
+          GIT_CONFIG_GLOBAL: "/dev/null",
+          GIT_OPTIONAL_LOCKS: "0",
+          GIT_NO_REPLACE_OBJECTS: "1",
+          GIT_PAGER: "cat",
+          GIT_TERMINAL_PROMPT: "0",
+        },
+      },
+    );
+    return result.stdout;
+  } catch {
+    const operation =
+      args[0] === "rev-parse"
+        ? "revision query"
+        : args[0] === "status"
+          ? "worktree status query"
+          : args[0] === "log"
+            ? "activity query"
+            : args[0] === "ls-tree"
+              ? "committed tree query"
+              : args[0] === "cat-file"
+                ? "committed object query"
+                : "immutable repository query";
+    throw new FleetGitSnapshotError(`Git ${operation} failed`);
+  }
+}
+
+function oneLine(value: string | Buffer, label: string): string {
+  const text = Buffer.isBuffer(value) ? value.toString("utf8") : value;
+  if (!text.endsWith("\n") || text.endsWith("\n\n")) {
+    throw new FleetGitSnapshotError(`${label} returned malformed line output`);
+  }
+  const line = text.slice(0, -1);
+  if (!line || /[\0\r\n]/u.test(line)) {
+    throw new FleetGitSnapshotError(`${label} returned an invalid value`);
+  }
+  return line;
+}
+
+function sha256(value: string | Buffer): string {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+function safeRelativePath(root: string, path: string): string {
+  if (!path || isAbsolute(path) || /[\0\r\n]/u.test(path)) {
+    throw new FleetGitSnapshotError("committed path is not one safe repository-relative path");
+  }
+  const normalized = relative(resolve(root), resolve(root, path)).split("\\").join("/");
+  if (!normalized || normalized.startsWith("../") || normalized === "..") {
+    throw new FleetGitSnapshotError("committed path escapes its repository snapshot");
+  }
+  return normalized;
+}
+
+async function captureHead(root: string): Promise<string> {
+  const head = oneLine(
+    await runGit(root, ["rev-parse", "--verify", "HEAD^{commit}"], "utf8"),
+    "HEAD",
+  );
+  if (!FULL_GIT_OID.test(head)) throw new FleetGitSnapshotError("HEAD is not a full Git object id");
+  return head;
+}
+
+async function captureStatus(root: string): Promise<Buffer> {
+  const output = await runGit(root, ["status", "--porcelain=v1", "-z", "--untracked-files=all"]);
+  return Buffer.isBuffer(output) ? output : Buffer.from(output, "utf8");
+}
+
+export async function verifyFleetGitRevision(
+  path: string,
+  revision: string,
+  options: { requiredFiles?: string[] } = {},
+): Promise<{ repoRoot: string; commit: string; treeOid: string; sourceRelative: string }> {
+  if (!FULL_GIT_OID.test(revision)) {
+    throw new FleetGitSnapshotError("template revision is not one full Git object id");
+  }
+  const canonical = await realpath(path).catch(() => undefined);
+  if (!canonical) throw new FleetGitSnapshotError("template source cannot be resolved");
+  const topRaw = oneLine(
+    await runGit(canonical, ["rev-parse", "--show-toplevel"], "utf8"),
+    "template Git top-level",
+  );
+  const repoRoot = await realpath(topRaw).catch(() => undefined);
+  if (!repoRoot) throw new FleetGitSnapshotError("template Git root cannot be resolved");
+  const sourceRelative = relative(repoRoot, canonical).split("\\").join("/");
+  if (!sourceRelative || sourceRelative.startsWith("../") || isAbsolute(sourceRelative)) {
+    throw new FleetGitSnapshotError("template source must be a subdirectory of its Git repository");
+  }
+  const commit = oneLine(
+    await runGit(repoRoot, ["rev-parse", "--verify", `${revision}^{commit}`], "utf8"),
+    "template revision",
+  );
+  if (commit !== revision)
+    throw new FleetGitSnapshotError("template revision did not resolve exactly");
+  const treeOid = oneLine(
+    await runGit(repoRoot, ["rev-parse", `${commit}^{tree}`], "utf8"),
+    "template tree",
+  );
+  if (!FULL_GIT_OID.test(treeOid)) throw new FleetGitSnapshotError("template tree is invalid");
+  for (const required of options.requiredFiles ?? []) {
+    const pathAtRevision = join(sourceRelative, safeRelativePath(canonical, required))
+      .split("\\")
+      .join("/");
+    const raw = await runGit(repoRoot, ["ls-tree", "-z", commit, "--", pathAtRevision]);
+    const listing = Buffer.isBuffer(raw) ? raw : Buffer.from(raw, "utf8");
+    const text = listing.subarray(0, -1).toString("utf8");
+    const tab = text.indexOf("\t");
+    const metadata = tab >= 0 ? text.slice(0, tab).split(" ") : [];
+    if (
+      listing.length === 0 ||
+      listing[listing.length - 1] !== 0 ||
+      text.slice(tab + 1) !== pathAtRevision ||
+      (metadata[0] !== "100644" && metadata[0] !== "100755") ||
+      metadata[1] !== "blob" ||
+      !FULL_GIT_OID.test(metadata[2] ?? "")
+    ) {
+      throw new FleetGitSnapshotError(`template revision lacks required file: ${required}`);
+    }
+  }
+  return { repoRoot, commit, treeOid, sourceRelative };
+}
+
+/** Resolve one exact Git repository root from a working directory (read-only). */
+export async function resolveGitRepoRoot(cwd: string): Promise<string> {
+  const { execFile } = await import("node:child_process");
+  const { promisify } = await import("node:util");
+  const stdout = await promisify(execFile)(
+    "git",
+    ["--no-pager", "-C", cwd, "rev-parse", "--show-toplevel"],
+    { timeout: 15_000, windowsHide: true, encoding: "utf8" },
+  );
+  const root = stdout.stdout.trim();
+  if (!root) throw new FleetGitSnapshotError("empty repository root");
+  return root;
+}
+
+export async function captureFleetGitSnapshot(repoRoot: string): Promise<FleetGitSnapshot> {
+  const root = await realpath(repoRoot).catch(() => undefined);
+  if (!root) throw new FleetGitSnapshotError("repository root cannot be resolved");
+  const topRaw = oneLine(
+    await runGit(root, ["rev-parse", "--show-toplevel"], "utf8"),
+    "Git top-level",
+  );
+  const top = await realpath(topRaw).catch(() => undefined);
+  if (top !== root) {
+    throw new FleetGitSnapshotError("candidate is not one exact Git repository root");
+  }
+
+  const commit = await captureHead(root);
+  const treeOid = oneLine(
+    await runGit(root, ["rev-parse", `${commit}^{tree}`], "utf8"),
+    "Git tree",
+  );
+  if (!FULL_GIT_OID.test(treeOid))
+    throw new FleetGitSnapshotError("tree is not a full Git object id");
+  const statusBytes = await captureStatus(root);
+  const statusSha256 = sha256(statusBytes);
+  const activityRaw = await runGit(
+    root,
+    ["log", "-1", "--format=%cI", commit, "--", "diary", "docs/learnings"],
+    "utf8",
+  );
+  const latestActivityAt = String(activityRaw).trim() || undefined;
+  const fileCache = new Map<string, CapturedGitFile | undefined>();
+
+  return {
+    root,
+    commit,
+    treeOid,
+    status: statusBytes.length === 0 ? "clean_observed" : "dirty",
+    statusSha256,
+    ...(latestActivityAt ? { latestActivityAt } : {}),
+    async readFile(path: string, maxBytes = 1024 * 1024) {
+      const relativePath = safeRelativePath(root, path);
+      if (fileCache.has(relativePath)) {
+        const cached = fileCache.get(relativePath);
+        if (cached && cached.bytes.length > maxBytes) {
+          throw new FleetGitSnapshotError(
+            `committed blob exceeds ${maxBytes} bytes: ${relativePath}`,
+          );
+        }
+        return cached;
+      }
+      const listingRaw = await runGit(root, ["ls-tree", "-z", commit, "--", relativePath]);
+      const listing = Buffer.isBuffer(listingRaw) ? listingRaw : Buffer.from(listingRaw, "utf8");
+      if (listing.length === 0) {
+        fileCache.set(relativePath, undefined);
+        return undefined;
+      }
+      const records = listing
+        .subarray(0, listing.length - 1)
+        .toString("utf8")
+        .split("\0");
+      if (!listing.subarray(-1).equals(Buffer.from([0])) || records.length !== 1) {
+        throw new FleetGitSnapshotError(`committed path is ambiguous: ${relativePath}`);
+      }
+      const separator = records[0]?.indexOf("\t") ?? -1;
+      const metadata = separator >= 0 ? records[0]?.slice(0, separator).split(" ") : [];
+      const listedPath = separator >= 0 ? records[0]?.slice(separator + 1) : undefined;
+      const [mode, type, blobOid] = metadata;
+      if (
+        listedPath !== relativePath ||
+        type !== "blob" ||
+        !mode ||
+        !blobOid ||
+        !FULL_GIT_OID.test(blobOid)
+      ) {
+        throw new FleetGitSnapshotError(`committed path is not one exact blob: ${relativePath}`);
+      }
+      if (mode !== "100644" && mode !== "100755") {
+        fileCache.set(relativePath, undefined);
+        return undefined;
+      }
+      const size = Number.parseInt(
+        oneLine(
+          await runGit(root, ["cat-file", "-s", blobOid], "utf8"),
+          `blob size ${relativePath}`,
+        ),
+        10,
+      );
+      if (!Number.isSafeInteger(size) || size < 0 || size > maxBytes) {
+        throw new FleetGitSnapshotError(
+          `committed blob exceeds ${maxBytes} bytes: ${relativePath}`,
+        );
+      }
+      const raw = await runGit(root, ["cat-file", "blob", blobOid]);
+      const bytes = Buffer.isBuffer(raw) ? raw : Buffer.from(raw, "utf8");
+      if (bytes.length !== size) {
+        throw new FleetGitSnapshotError(
+          `committed blob size changed during capture: ${relativePath}`,
+        );
+      }
+      const captured = { path: relativePath, mode, blobOid, bytes, sha256: sha256(bytes) };
+      fileCache.set(relativePath, captured);
+      return captured;
+    },
+    async finish() {
+      const [finalCommit, finalStatus] = await Promise.all([
+        captureHead(root),
+        captureStatus(root),
+      ]);
+      const finalStatusSha256 = sha256(finalStatus);
+      return {
+        stable: finalCommit === commit && finalStatusSha256 === statusSha256,
+        finalCommit,
+        finalStatusSha256,
+      };
+    },
+  };
+}

package/src/fleet-lint-provenance.ts

@@ -0,0 +1,356 @@
+// ---
+// summary: bounded template provenance and exact-role collision helpers for fleet lint.
+// read_when:
+//   - changing Copier lineage diagnostics, template ownership recognition, or role normalization.
+// ---
+
+import { basename, isAbsolute, resolve } from "node:path";
+import { type FleetGitSnapshot, verifyFleetGitRevision } from "./fleet-git-snapshot.ts";
+import type { FleetLintDiagnostic, FleetLintRepositoryResult } from "./fleet-lint-types.ts";
+
+const FULL_REVISION = /^[0-9a-f]{40,64}$/u;
+const ANSWERS_PATH = ".copier-answers.yml";
+const OWNERSHIP_PATH = "contracts/template-ownership.yml";
+
+function decodeOwnerUtf8(bytes: Buffer, label: string): string {
+  try {
+    return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+  } catch {
+    throw new Error(`${label} is not strict UTF-8`);
+  }
+}
+
+function isPythonWhitespace(code: number): boolean {
+  return (
+    (code >= 0x0009 && code <= 0x000d) ||
+    (code >= 0x001c && code <= 0x001f) ||
+    code === 0x0020 ||
+    code === 0x0085 ||
+    code === 0x00a0 ||
+    code === 0x1680 ||
+    (code >= 0x2000 && code <= 0x200a) ||
+    code === 0x2028 ||
+    code === 0x2029 ||
+    code === 0x202f ||
+    code === 0x205f ||
+    code === 0x3000
+  );
+}
+
+function pythonStrip(value: string): string {
+  let start = 0;
+  let end = value.length;
+  while (start < end && isPythonWhitespace(value.charCodeAt(start))) start += 1;
+  while (end > start && isPythonWhitespace(value.charCodeAt(end - 1))) end -= 1;
+  return value.slice(start, end);
+}
+
+function pythonSplitLines(value: string): string[] {
+  const lines: string[] = [];
+  let current = "";
+  for (let index = 0; index < value.length; index += 1) {
+    const code = value.charCodeAt(index);
+    const separator =
+      code === 10 ||
+      code === 11 ||
+      code === 12 ||
+      code === 13 ||
+      (code >= 28 && code <= 30) ||
+      code === 133 ||
+      code === 8232 ||
+      code === 8233;
+    if (!separator) {
+      current += value[index];
+      continue;
+    }
+    lines.push(current);
+    current = "";
+    if (code === 13 && value.charCodeAt(index + 1) === 10) index += 1;
+  }
+  if (current) lines.push(current);
+  return lines;
+}
+
+function parseCopierScalar(raw: string, label: string): string {
+  if (!raw || "!&*|>{[".includes(raw[0] ?? "")) {
+    throw new Error(`${label} uses unsupported YAML syntax`);
+  }
+  let value: unknown;
+  if (raw.startsWith('"')) {
+    try {
+      value = JSON.parse(raw);
+    } catch {
+      throw new Error(`${label} has invalid double-quoted syntax`);
+    }
+  } else if (raw.startsWith("'")) {
+    if (raw.length < 2 || !raw.endsWith("'")) {
+      throw new Error(`${label} has invalid single-quoted syntax`);
+    }
+    value = raw.slice(1, -1).replace(/''/gu, "'");
+  } else {
+    if (raw.includes(" #")) throw new Error(`${label} cannot contain an inline comment`);
+    value = raw;
+  }
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(`${label} must be one non-empty scalar`);
+  }
+  return value;
+}
+
+function copierScalar(text: string, key: string, required = false): string | undefined {
+  const prefix = `${key}:`;
+  const values = pythonSplitLines(text)
+    .filter((line) => line.startsWith(prefix))
+    .map((line) => pythonStrip(line.slice(prefix.length)));
+  if (values.length === 0) {
+    if (required) throw new Error(`${key} must occur exactly once`);
+    return undefined;
+  }
+  if (values.length !== 1) throw new Error(`${key} must occur exactly once`);
+  return parseCopierScalar(values[0] ?? "", key);
+}
+
+export function parseFleetCopierSource(text: string): string {
+  const source = copierScalar(text, "_src_path", true);
+  if (source === undefined) throw new Error("_src_path must occur exactly once");
+  return source;
+}
+
+function ownershipPatternsOverlap(left: string, right: string): boolean {
+  const leftPrefix = left.endsWith("/**") ? left.slice(0, -3).replace(/\/+$/u, "") : undefined;
+  const rightPrefix = right.endsWith("/**") ? right.slice(0, -3).replace(/\/+$/u, "") : undefined;
+  if (leftPrefix === undefined && rightPrefix === undefined) return left === right;
+  if (leftPrefix !== undefined && rightPrefix !== undefined) {
+    return (
+      leftPrefix === rightPrefix ||
+      leftPrefix.startsWith(`${rightPrefix}/`) ||
+      rightPrefix.startsWith(`${leftPrefix}/`)
+    );
+  }
+  if (leftPrefix !== undefined) return right === leftPrefix || right.startsWith(`${leftPrefix}/`);
+  return left === rightPrefix || left.startsWith(`${rightPrefix}/`);
+}
+
+export function parseFleetTemplateOwnership(text: string): {
+  templateOwned: string[];
+  agentOwned: string[];
+} {
+  let section: "template_owned" | "agent_owned" | undefined;
+  let schema = "";
+  const sections = { template_owned: [] as string[], agent_owned: [] as string[] };
+  for (const [index, raw] of pythonSplitLines(text).entries()) {
+    const line = pythonStrip(raw);
+    if (!line || line.startsWith("#")) continue;
+    if (raw === line && line.startsWith("schema:")) {
+      schema = pythonStrip(line.slice("schema:".length));
+      section = undefined;
+      continue;
+    }
+    if (raw === line && (line === "template_owned:" || line === "agent_owned:")) {
+      section = line.slice(0, -1) as typeof section;
+      continue;
+    }
+    if (section && raw.startsWith("  - ")) {
+      const pattern = pythonStrip(raw.slice(4));
+      if (!pattern || pattern.startsWith("/") || pattern.split("/").includes("..")) {
+        throw new Error(`invalid ownership pattern at line ${index + 1}`);
+      }
+      sections[section].push(pattern);
+      continue;
+    }
+    throw new Error(`unsupported ownership syntax at line ${index + 1}`);
+  }
+  if (schema !== "ai-society.template-ownership/1") {
+    throw new Error("unsupported template ownership schema");
+  }
+  if (sections.template_owned.length === 0 || sections.agent_owned.length === 0) {
+    throw new Error("ownership map requires non-empty template_owned and agent_owned lists");
+  }
+  for (const [name, patterns] of Object.entries(sections)) {
+    if (new Set(patterns).size !== patterns.length) {
+      throw new Error(`duplicate pattern in ${name}`);
+    }
+  }
+  for (const templatePattern of sections.template_owned) {
+    for (const agentPattern of sections.agent_owned) {
+      if (ownershipPatternsOverlap(templatePattern, agentPattern)) {
+        throw new Error(`ambiguous ownership patterns: ${templatePattern} and ${agentPattern}`);
+      }
+    }
+  }
+  return { templateOwned: sections.template_owned, agentOwned: sections.agent_owned };
+}
+
+export function validateFleetTemplateOwnershipPolicy(parsed: {
+  templateOwned: string[];
+  agentOwned: string[];
+}): void {
+  const requiredAgentOwned = [".copier-answers.yml", "agent.json", "docs/person/**"];
+  if (requiredAgentOwned.some((entry) => !parsed.agentOwned.includes(entry))) {
+    throw new Error("required agent-owned manifest/persona paths are missing");
+  }
+}
+
+export function normalizeFleetRole(value: string): string {
+  return value.normalize("NFKC").trim().toLowerCase().replace(/\s+/gu, " ");
+}
+
+export async function inspectTemplateProvenance(params: {
+  snapshot: FleetGitSnapshot;
+  repoName: string;
+}): Promise<{
+  template: FleetLintRepositoryResult["template"];
+  diagnostics: FleetLintDiagnostic[];
+}> {
+  const diagnostics: FleetLintDiagnostic[] = [];
+  const [answersResult, ownershipResult] = await Promise.allSettled([
+    params.snapshot.readFile(ANSWERS_PATH, 64 * 1024),
+    params.snapshot.readFile(OWNERSHIP_PATH, 64 * 1024),
+  ]);
+  const answers = answersResult.status === "fulfilled" ? answersResult.value : undefined;
+  const ownership = ownershipResult.status === "fulfilled" ? ownershipResult.value : undefined;
+  const answersCaptureFailed = answersResult.status === "rejected";
+  const ownershipCaptureFailed = ownershipResult.status === "rejected";
+  const template: FleetLintRepositoryResult["template"] = {
+    mode: ownership ? "managed_v2" : answers && !ownershipCaptureFailed ? "legacy" : "unknown",
+    provenanceStatus: answersCaptureFailed || ownershipCaptureFailed ? "invalid" : "unbound",
+    ...(answers ? { answersSha256: answers.sha256 } : {}),
+    ...(ownership ? { ownershipSha256: ownership.sha256 } : {}),
+  };
+
+  if (ownershipCaptureFailed) {
+    diagnostics.push({
+      code: "template.ownership_capture_failed",
+      severity: "error",
+      repo: params.repoName,
+      path: OWNERSHIP_PATH,
+      message: "committed template ownership bytes could not be captured within the lint bound",
+    });
+  }
+  if (answersCaptureFailed) {
+    diagnostics.push({
+      code: "template.answers_capture_failed",
+      severity: "error",
+      repo: params.repoName,
+      path: ANSWERS_PATH,
+      message: "committed Copier provenance bytes could not be captured within the lint bound",
+    });
+  }
+
+  if (ownership) {
+    try {
+      const parsed = parseFleetTemplateOwnership(
+        decodeOwnerUtf8(ownership.bytes, "template ownership"),
+      );
+      validateFleetTemplateOwnershipPolicy(parsed);
+    } catch {
+      template.provenanceStatus = "invalid";
+      diagnostics.push({
+        code: "template.ownership_invalid",
+        severity: "error",
+        repo: params.repoName,
+        path: OWNERSHIP_PATH,
+        message: "template ownership does not satisfy the ratified parser and fleet path policy",
+      });
+    }
+  }
+
+  if (!answers) {
+    if (!answersCaptureFailed) {
+      diagnostics.push({
+        code: "template.provenance_missing",
+        severity: "warning",
+        repo: params.repoName,
+        path: ANSWERS_PATH,
+        message: "repository has no committed Copier provenance answers",
+        hint: "provenance remains unverifiable; do not re-render or infer template currentness",
+      });
+    }
+    return { template, diagnostics };
+  }
+
+  let answersText: string;
+  try {
+    answersText = decodeOwnerUtf8(answers.bytes, "Copier answers");
+  } catch {
+    template.provenanceStatus = "invalid";
+    diagnostics.push({
+      code: "template.answers_invalid",
+      severity: "error",
+      repo: params.repoName,
+      path: ANSWERS_PATH,
+      message: "committed Copier provenance is not strict UTF-8",
+    });
+    return { template, diagnostics };
+  }
+
+  let sourcePath: string | undefined;
+  let revision: string | undefined;
+  try {
+    sourcePath = parseFleetCopierSource(answersText);
+    revision =
+      copierScalar(answersText, "template_source_sha") ??
+      copierScalar(answersText, "l0_source_sha") ??
+      copierScalar(answersText, "_commit");
+  } catch {
+    template.provenanceStatus = "invalid";
+    diagnostics.push({
+      code: "template.answers_invalid",
+      severity: "error",
+      repo: params.repoName,
+      path: ANSWERS_PATH,
+      message: "committed Copier provenance uses unsupported or ambiguous scalar syntax",
+    });
+    return { template, diagnostics };
+  }
+  const resolvedSourcePath = sourcePath
+    ? isAbsolute(sourcePath)
+      ? sourcePath
+      : resolve(params.snapshot.root, sourcePath)
+    : undefined;
+  if (revision && FULL_REVISION.test(revision)) template.sourceRevision = revision;
+  if (
+    revision &&
+    FULL_REVISION.test(revision) &&
+    resolvedSourcePath &&
+    basename(resolvedSourcePath) === "tpl-agent-repo"
+  ) {
+    try {
+      const verified = await verifyFleetGitRevision(resolvedSourcePath, revision, {
+        requiredFiles: [
+          "agent.json.j2",
+          "copier.yml",
+          "contracts/template-ownership.yml",
+          "scripts/compile-system-prompt.py",
+        ],
+      });
+      template.sourcePath = `${basename(verified.repoRoot) || "root"}/${verified.sourceRelative}`;
+      template.sourceTreeOid = verified.treeOid;
+      if (template.provenanceStatus !== "invalid") {
+        template.provenanceStatus = "verified_local_source";
+      }
+    } catch {
+      diagnostics.push({
+        code: "template.revision_unverifiable",
+        severity: template.mode === "managed_v2" ? "error" : "warning",
+        repo: params.repoName,
+        path: ANSWERS_PATH,
+        message: "declared local template source revision could not be verified",
+        hint: "a declared revision is not matched until the exact source Git object is locally verifiable",
+      });
+    }
+  } else {
+    diagnostics.push({
+      code: revision ? "template.revision_invalid" : "template.revision_unbound",
+      severity: template.mode === "managed_v2" ? "error" : "warning",
+      repo: params.repoName,
+      path: ANSWERS_PATH,
+      message:
+        revision && !FULL_REVISION.test(revision)
+          ? "template provenance revision is not one full immutable Git object id"
+          : "template provenance lacks a verifiable source path and immutable revision",
+      hint: "record exact source revision only through the owning template propagation contract",
+    });
+  }
+  return { template, diagnostics };
+}