harnery 0.33.0 → 0.34.0

package/dist/lib/docs-lint.js

@@ -1,6 +1,7 @@
 import { existsSync as __existsSyncForDocs } from "node:fs";
 import { resolve as __resolveForDocs } from "node:path";
 import { hasYamlStatus } from "./docs-frontmatter.js";
+import { initDocsMetadataAuditContext, runDocsMetadataAudit } from "./docs-metadata-audit.js";
 import { sh } from "./exec.js";
 // Module-level docs context, initialized by initDocsContext() before any
 // other function in this file is called. Consumers pass repo metadata
@@ -15,6 +16,7 @@ export function initDocsContext(opts) {
     SUBMODULES = opts.submodules;
     EXTRA_EXCLUDED_PREFIXES = opts.extraExcludedPrefixes ?? [];
     DOCS_ROOT_ALLOWLIST = opts.docsRootAllowlist ?? [];
+    initDocsMetadataAuditContext({ repoRoot: opts.repoRoot, submodules: opts.submodules });
 }
 function submodulePath(name) {
     return __resolveForDocs(REPO_ROOT, name);
@@ -351,35 +353,6 @@ function checkChangelogNames(repoName, _repoPath, files) {
     }
     return violations;
 }
-/** Plans, issues, and handoffs must carry YAML lifecycle status (content check, slow). */
-function checkStatusHeaders(repoName, repoPath, files) {
-    const violations = [];
-    const targetDirs = ["docs/plans/", "docs/issues/", "docs/handoffs/"];
-    for (const rel of files) {
-        const dirMatch = targetDirs.some((d) => rel.startsWith(d));
-        if (!dirMatch)
-            continue;
-        const name = basename(rel);
-        if (name === "README.md")
-            continue;
-        const full = join(repoPath, rel);
-        if (!hasStatusHeader(full)) {
-            const kind = rel.startsWith("docs/plans/")
-                ? "plan"
-                : rel.startsWith("docs/issues/")
-                    ? "issue"
-                    : "handoff";
-            violations.push({
-                severity: "error",
-                repo: repoName,
-                path: join(repoName === "(root)" ? "" : repoName, rel),
-                rule: "missing-status-header",
-                message: `${kind} missing status in leading YAML frontmatter`,
-            });
-        }
-    }
-    return violations;
-}
 /** Intentional monoliths >30KB need a declaration banner */
 function checkMonolithDeclaration(repoName, repoPath, files) {
     const violations = [];
@@ -434,9 +407,20 @@ export async function runLint(opts) {
         violations.push(...checkDatedDirs(name, path, files));
         violations.push(...checkChangelogNames(name, path, files));
         if (!opts.fast) {
-            violations.push(...checkStatusHeaders(name, path, files));
             violations.push(...checkMonolithDeclaration(name, path, files));
         }
     }
+    const metadataRows = await runDocsMetadataAudit({ repo: opts.repo });
+    for (const row of metadataRows) {
+        for (const issue of row.issues.filter((entry) => entry.severity === "error")) {
+            violations.push({
+                severity: "error",
+                repo: row.repo,
+                path: row.path,
+                rule: `metadata-v2:${issue.code}`,
+                message: issue.field ? `${issue.field}: ${issue.message}` : issue.message,
+            });
+        }
+    }
     return violations;
 }

package/dist/lib/docs-metadata-audit.d.ts

@@ -0,0 +1,19 @@
+import { type DocsMetadataProfile, type DocsMetadataValidationIssue } from "./docs-metadata-v2.js";
+export declare function initDocsMetadataAuditContext(opts: {
+    repoRoot: string;
+    submodules: readonly string[];
+}): void;
+export interface DocsMetadataAuditOpts {
+    repo?: string;
+}
+export type DocsMetadataAuditState = "valid" | "invalid" | "legacy" | "missing";
+export interface DocsMetadataAuditRow {
+    repo: string;
+    path: string;
+    state: DocsMetadataAuditState;
+    profile: DocsMetadataProfile | null;
+    issues: DocsMetadataValidationIssue[];
+}
+export declare function runDocsMetadataAudit(opts: DocsMetadataAuditOpts): Promise<DocsMetadataAuditRow[]>;
+export declare function auditDocsMetadataText(content: string, path: string): DocsMetadataAuditRow | null;
+//# sourceMappingURL=docs-metadata-audit.d.ts.map

package/dist/lib/docs-metadata-audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-metadata-audit.d.ts","sourceRoot":"","sources":["../../src/lib/docs-metadata-audit.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,2BAA2B,EAIjC,MAAM,uBAAuB,CAAC;AAM/B,wBAAgB,4BAA4B,CAAC,IAAI,EAAE;IACjD,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;CAC/B,GAAG,IAAI,CAGP;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,sBAAsB,GAAG,OAAO,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEhF,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,sBAAsB,CAAC;IAC9B,OAAO,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACpC,MAAM,EAAE,2BAA2B,EAAE,CAAC;CACvC;AAuED,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,qBAAqB,GAC1B,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAqBjC;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,oBAAoB,GAAG,IAAI,CAiChG"}

package/dist/lib/docs-metadata-audit.js

@@ -0,0 +1,132 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import { parseFrontmatter } from "./docs-frontmatter.js";
+import { isManagedDocsMetadataFile, managedDocsMetadataType } from "./docs-metadata-managed.js";
+import { docsMetadataProfileForType, isDocsMetadataV2, validateDocsMetadataV2, } from "./docs-metadata-v2.js";
+import { sh } from "./exec.js";
+let REPO_ROOT = "";
+let SUBMODULES = [];
+export function initDocsMetadataAuditContext(opts) {
+    REPO_ROOT = opts.repoRoot;
+    SUBMODULES = opts.submodules;
+}
+function isInitializedRepo(path) {
+    return existsSync(join(path, ".git"));
+}
+async function trackedMarkdownFiles(repoPath) {
+    const result = await sh('git ls-files --cached "**/*.md" "*.md"', { cwd: repoPath });
+    if (result.exitCode !== 0 || !result.stdout.trim())
+        return [];
+    return result.stdout
+        .trim()
+        .split("\n")
+        .filter((path) => path.endsWith(".md"));
+}
+function auditFile(repoName, repoPath, path) {
+    let content;
+    try {
+        content = readFileSync(join(repoPath, path), "utf8");
+    }
+    catch {
+        return {
+            repo: repoName,
+            path: join(repoName === "(root)" ? "" : repoName, path),
+            state: "missing",
+            profile: null,
+            issues: [
+                {
+                    severity: "error",
+                    code: "file_unreadable",
+                    field: "",
+                    message: "metadata file could not be read",
+                },
+            ],
+        };
+    }
+    const { data, raw } = parseFrontmatter(content);
+    const displayPath = join(repoName === "(root)" ? "" : repoName, path);
+    if (!isManagedDocsMetadataFile(path, data, raw !== null))
+        return null;
+    const expectedType = managedDocsMetadataType(path, data, raw !== null);
+    if (isDocsMetadataV2(data)) {
+        const result = validateDocsMetadataV2(data);
+        return {
+            repo: repoName,
+            path: displayPath,
+            state: result.valid ? "valid" : "invalid",
+            profile: result.profile,
+            issues: result.issues,
+        };
+    }
+    const state = raw === null ? "missing" : "legacy";
+    return {
+        repo: repoName,
+        path: displayPath,
+        state,
+        profile: expectedType ? docsMetadataProfileForType(expectedType) : null,
+        issues: [
+            {
+                severity: "error",
+                code: state === "missing" ? "missing_metadata" : "legacy_schema",
+                field: "schema",
+                message: state === "missing"
+                    ? "required document has no leading YAML metadata"
+                    : "document still uses pre-v2 metadata",
+            },
+        ],
+    };
+}
+export async function runDocsMetadataAudit(opts) {
+    const targets = [
+        { name: "(root)", path: REPO_ROOT },
+        ...SUBMODULES.map((name) => ({ name, path: resolve(REPO_ROOT, name) })).filter((target) => isInitializedRepo(target.path)),
+    ];
+    const filter = opts.repo === "." ? "(root)" : opts.repo;
+    const selected = filter ? targets.filter((target) => target.name === filter) : targets;
+    if (filter && selected.length === 0)
+        throw new Error(`Unknown repository: ${opts.repo}`);
+    const rows = [];
+    for (const target of selected) {
+        const files = await trackedMarkdownFiles(target.path);
+        for (const path of files) {
+            const row = auditFile(target.name, target.path, path);
+            if (row)
+                rows.push(row);
+        }
+    }
+    return rows.sort((a, b) => a.path.localeCompare(b.path));
+}
+export function auditDocsMetadataText(content, path) {
+    const root = resolve("/");
+    const parsed = parseFrontmatter(content);
+    if (!isManagedDocsMetadataFile(path, parsed.data, parsed.raw !== null))
+        return null;
+    const expectedType = managedDocsMetadataType(path, parsed.data, parsed.raw !== null);
+    if (isDocsMetadataV2(parsed.data)) {
+        const result = validateDocsMetadataV2(parsed.data);
+        return {
+            repo: "(root)",
+            path: relative(root, resolve(root, path)),
+            state: result.valid ? "valid" : "invalid",
+            profile: result.profile,
+            issues: result.issues,
+        };
+    }
+    const state = parsed.raw === null ? "missing" : "legacy";
+    return {
+        repo: "(root)",
+        path,
+        state,
+        profile: expectedType ? docsMetadataProfileForType(expectedType) : null,
+        issues: [
+            {
+                severity: "error",
+                code: state === "missing" ? "missing_metadata" : "legacy_schema",
+                field: "schema",
+                message: state === "missing"
+                    ? "required document has no leading YAML metadata"
+                    : "document still uses pre-v2 metadata",
+            },
+        ],
+    };
+}

package/dist/lib/docs-metadata-managed.d.ts

@@ -0,0 +1,23 @@
+import { type DocsMetadataType } from "./docs-metadata-v2.js";
+/**
+ * Paths whose Markdown carries frontmatter belonging to another system:
+ * generated mirrors of documents that live elsewhere, vendored vendor
+ * specifications, and the placeholder headers inside document templates.
+ */
+export declare function isExcludedDocsMetadataPath(path: string): boolean;
+/**
+ * Return the v2 type expected for a Markdown file that participates in the
+ * managed metadata contract. Unmanaged Markdown and unrelated YAML-frontmatter
+ * systems return null.
+ */
+export declare function managedDocsMetadataType(path: string, data: Record<string, unknown>, hasFrontmatter: boolean): DocsMetadataType | null;
+/**
+ * Whether a Markdown file has to satisfy the v2 contract.
+ *
+ * A file that claims the v2 schema marker is always checked, even when its
+ * `type` is missing or misspelled. Deciding membership from the type alone
+ * let a typo drop the document out of the audit entirely, so an invalid
+ * header reported as nothing rather than as an error.
+ */
+export declare function isManagedDocsMetadataFile(path: string, data: Record<string, unknown>, hasFrontmatter: boolean): boolean;
+//# sourceMappingURL=docs-metadata-managed.d.ts.map

package/dist/lib/docs-metadata-managed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-metadata-managed.d.ts","sourceRoot":"","sources":["../../src/lib/docs-metadata-managed.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,gBAAgB,EAAwC,MAAM,uBAAuB,CAAC;AAMpG;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAUhE;AAmBD;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,cAAc,EAAE,OAAO,GACtB,gBAAgB,GAAG,IAAI,CAczB;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,cAAc,EAAE,OAAO,GACtB,OAAO,CAIT"}

package/dist/lib/docs-metadata-managed.js

@@ -0,0 +1,78 @@
+import { basename } from "node:path";
+import { isDocsMetadataType, isDocsMetadataV2 } from "./docs-metadata-v2.js";
+function normalized(path) {
+    return path.replaceAll("\\", "/");
+}
+/**
+ * Paths whose Markdown carries frontmatter belonging to another system:
+ * generated mirrors of documents that live elsewhere, vendored vendor
+ * specifications, and the placeholder headers inside document templates.
+ */
+export function isExcludedDocsMetadataPath(path) {
+    const rel = normalized(path);
+    const segments = rel.split("/");
+    return (segments.includes(".wiki-data") ||
+        // Dashboard surfaces render from copies of other repositories' documents.
+        /(?:^|\/)content\/dashboards\//.test(rel) ||
+        /(?:^|\/)docs\/shopify\/admin-api\//.test(rel) ||
+        /(?:^|\/)docs\/templates\//.test(rel));
+}
+function lifecycleType(path) {
+    const rel = normalized(path);
+    if (basename(rel).toLowerCase() === "readme.md")
+        return null;
+    // A repository may sit at any depth inside the host checkout, so the
+    // directory rules anchor on `docs/<kind>/` rather than a single optional
+    // path segment. A one-segment-only prefix hid every document in a
+    // repository nested two or more levels down.
+    if (/(?:^|\/)docs\/plans\//.test(rel))
+        return "plan";
+    if (/(?:^|\/)docs\/issues\//.test(rel))
+        return "issue";
+    if (/(?:^|\/)docs\/coordination\/issues\//.test(rel))
+        return "issue";
+    if (/(?:^|\/)docs\/handoffs\//.test(rel))
+        return "handoff";
+    if (/(?:^|\/)docs\/audits\//.test(rel))
+        return "audit";
+    if (/^harnery-dev\/plans\//.test(rel))
+        return "plan";
+    if (/^harnery-dev\/issues\//.test(rel))
+        return "issue";
+    return null;
+}
+/**
+ * Return the v2 type expected for a Markdown file that participates in the
+ * managed metadata contract. Unmanaged Markdown and unrelated YAML-frontmatter
+ * systems return null.
+ */
+export function managedDocsMetadataType(path, data, hasFrontmatter) {
+    const rel = normalized(path);
+    if (isExcludedDocsMetadataPath(rel))
+        return null;
+    if (isDocsMetadataType(data.type))
+        return data.type;
+    const lifecycle = lifecycleType(rel);
+    if (lifecycle)
+        return lifecycle;
+    const name = basename(rel).toLowerCase();
+    if (/(?:^|\/)docs\/runbook\.md$/.test(rel) || (hasFrontmatter && /^.+-runbook\.md$/.test(name))) {
+        return "runbook";
+    }
+    return null;
+}
+/**
+ * Whether a Markdown file has to satisfy the v2 contract.
+ *
+ * A file that claims the v2 schema marker is always checked, even when its
+ * `type` is missing or misspelled. Deciding membership from the type alone
+ * let a typo drop the document out of the audit entirely, so an invalid
+ * header reported as nothing rather than as an error.
+ */
+export function isManagedDocsMetadataFile(path, data, hasFrontmatter) {
+    if (isExcludedDocsMetadataPath(path))
+        return false;
+    if (isDocsMetadataV2(data))
+        return true;
+    return managedDocsMetadataType(path, data, hasFrontmatter) !== null;
+}

package/dist/lib/docs-metadata-sync.d.ts

@@ -0,0 +1,20 @@
+export declare function initDocsMetadataSyncContext(opts: {
+    repoRoot: string;
+    submodules: readonly string[];
+}): void;
+export interface DocsMetadataSyncOpts {
+    repo?: string;
+    files?: string[];
+    check?: boolean;
+    reviewed?: boolean;
+    now?: string;
+}
+export interface DocsMetadataSyncRow {
+    repo: string;
+    path: string;
+    status: "unchanged" | "updated" | "drift" | "invalid";
+    fields: string[];
+    message?: string;
+}
+export declare function runDocsMetadataSync(opts: DocsMetadataSyncOpts): Promise<DocsMetadataSyncRow[]>;
+//# sourceMappingURL=docs-metadata-sync.d.ts.map

package/dist/lib/docs-metadata-sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-metadata-sync.d.ts","sourceRoot":"","sources":["../../src/lib/docs-metadata-sync.ts"],"names":[],"mappings":"AAWA,wBAAgB,2BAA2B,CAAC,IAAI,EAAE;IAChD,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;CAC/B,GAAG,IAAI,CAGP;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;IACtD,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAyED,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,oBAAoB,GACzB,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAyJhC"}

package/dist/lib/docs-metadata-sync.js

@@ -0,0 +1,222 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { dump as dumpYaml, JSON_SCHEMA } from "js-yaml";
+import { parseFrontmatter } from "./docs-frontmatter.js";
+import { managedDocsMetadataType } from "./docs-metadata-managed.js";
+import { isDocsMetadataV2, validateDocsMetadataV2 } from "./docs-metadata-v2.js";
+import { sh } from "./exec.js";
+let REPO_ROOT = "";
+let SUBMODULES = [];
+export function initDocsMetadataSyncContext(opts) {
+    REPO_ROOT = opts.repoRoot;
+    SUBMODULES = opts.submodules;
+}
+function targets(repo) {
+    const all = [
+        { name: "(root)", path: REPO_ROOT },
+        ...SUBMODULES.filter((name) => existsSync(join(REPO_ROOT, name, ".git"))).map((name) => ({
+            name,
+            path: resolve(REPO_ROOT, name),
+        })),
+    ];
+    const filter = repo === "." ? "(root)" : repo;
+    const selected = filter ? all.filter((target) => target.name === filter) : all;
+    if (filter && selected.length === 0)
+        throw new Error(`Unknown repository: ${repo}`);
+    return selected;
+}
+async function changedFiles(target, explicit) {
+    if (explicit.length > 0)
+        return explicit;
+    const result = await sh("git diff --cached --name-only --diff-filter=ACMR -- '*.md'", {
+        cwd: target.path,
+    });
+    if (result.exitCode !== 0)
+        throw new Error(result.stderr || "git diff failed");
+    return result.stdout.split("\n").filter(Boolean);
+}
+async function headContent(target, path) {
+    const result = await sh(`git show HEAD:${JSON.stringify(path)}`, { cwd: target.path });
+    return result.exitCode === 0 ? result.stdout : null;
+}
+function semanticMetadata(data) {
+    const copy = { ...data };
+    delete copy.created_at;
+    delete copy.updated_at;
+    delete copy.status_changed_at;
+    delete copy.reviewed_at;
+    delete copy.review_due_at;
+    delete copy.source_updated_at;
+    delete copy.resolved_at;
+    return copy;
+}
+function semanticChanged(before, after) {
+    if (!before || !isDocsMetadataV2(before.data))
+        return false;
+    return (JSON.stringify(semanticMetadata(before.data)) !==
+        JSON.stringify(semanticMetadata(after.data)) ||
+        before.body.replaceAll("\r\n", "\n").trimEnd() !== after.body.replaceAll("\r\n", "\n").trimEnd());
+}
+function serialize(data, body) {
+    const yaml = dumpYaml(data, {
+        schema: JSON_SCHEMA,
+        noRefs: true,
+        lineWidth: -1,
+        sortKeys: false,
+        quotingType: '"',
+    }).trimEnd();
+    return `---\n${yaml}\n---\n${body.replace(/^\n+/, "\n")}`;
+}
+function addDays(value, days) {
+    const date = new Date(value);
+    date.setUTCDate(date.getUTCDate() + days);
+    return date.toISOString().replace(".000Z", "Z");
+}
+export async function runDocsMetadataSync(opts) {
+    const now = opts.now ?? new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+    const rows = [];
+    for (const target of targets(opts.repo)) {
+        for (const path of await changedFiles(target, opts.files ?? [])) {
+            const full = join(target.path, path);
+            if (!existsSync(full))
+                continue;
+            const currentText = readFileSync(full, "utf8");
+            const current = parseFrontmatter(currentText);
+            if (!managedDocsMetadataType(path, current.data, current.raw !== null))
+                continue;
+            if (!isDocsMetadataV2(current.data)) {
+                rows.push({
+                    repo: target.name,
+                    path,
+                    status: "invalid",
+                    fields: [],
+                    message: "managed document must use harnery-doc/v2",
+                });
+                continue;
+            }
+            const beforeText = await headContent(target, path);
+            const before = beforeText === null ? null : parseFrontmatter(beforeText);
+            const contentChanged = semanticChanged(before, current);
+            const beforeV2 = before !== null && isDocsMetadataV2(before.data) ? before.data : null;
+            const statusChanged = beforeV2 !== null && beforeV2.status !== current.data.status;
+            const fields = [];
+            const expected = { ...current.data };
+            if (contentChanged) {
+                expected.updated_at = now;
+                fields.push("updated_at");
+            }
+            if (statusChanged) {
+                expected.status_changed_at = now;
+                fields.push("status_changed_at");
+                if (current.data.status === "resolved" && current.data.type === "issue") {
+                    expected.resolved_at = now;
+                    fields.push("resolved_at");
+                }
+            }
+            if (!statusChanged &&
+                beforeV2 &&
+                current.data.status_changed_at !== beforeV2.status_changed_at) {
+                expected.status_changed_at = beforeV2.status_changed_at;
+                fields.push("status_changed_at");
+            }
+            if (opts.reviewed) {
+                if (current.data.type !== "runbook") {
+                    rows.push({
+                        repo: target.name,
+                        path,
+                        status: "invalid",
+                        fields: [],
+                        message: "--reviewed applies only to runbooks",
+                    });
+                    continue;
+                }
+                expected.reviewed_at = now;
+                expected.review_due_at = addDays(now, 180);
+                expected.updated_at = now;
+                fields.push("reviewed_at", "review_due_at", "updated_at");
+            }
+            if (beforeV2 && expected.created_at !== beforeV2.created_at) {
+                rows.push({
+                    repo: target.name,
+                    path,
+                    status: "invalid",
+                    fields: ["created_at"],
+                    message: "created_at is immutable",
+                });
+                continue;
+            }
+            if (opts.check) {
+                const validation = validateDocsMetadataV2(current.data);
+                if (!validation.valid) {
+                    rows.push({
+                        repo: target.name,
+                        path,
+                        status: "invalid",
+                        fields,
+                        message: validation.issues
+                            .map((issue) => `${issue.field}: ${issue.message}`)
+                            .join("; "),
+                    });
+                    continue;
+                }
+                const drift = [];
+                if (beforeV2 && contentChanged && current.data.updated_at === beforeV2.updated_at) {
+                    drift.push("updated_at");
+                }
+                if (beforeV2 && statusChanged) {
+                    if (current.data.status_changed_at === beforeV2.status_changed_at) {
+                        drift.push("status_changed_at");
+                    }
+                    if (current.data.status_changed_at !== current.data.updated_at) {
+                        drift.push("status_changed_at");
+                    }
+                    if (current.data.type === "issue" &&
+                        current.data.status === "resolved" &&
+                        current.data.resolved_at !== current.data.status_changed_at) {
+                        drift.push("resolved_at");
+                    }
+                }
+                if (beforeV2 &&
+                    !statusChanged &&
+                    current.data.status_changed_at !== beforeV2.status_changed_at) {
+                    drift.push("status_changed_at");
+                }
+                if (opts.reviewed &&
+                    beforeV2 &&
+                    (current.data.reviewed_at === beforeV2.reviewed_at ||
+                        current.data.review_due_at !== addDays(String(current.data.reviewed_at), 180))) {
+                    drift.push("reviewed_at", "review_due_at");
+                }
+                const uniqueDrift = [...new Set(drift)];
+                rows.push({
+                    repo: target.name,
+                    path,
+                    status: uniqueDrift.length ? "drift" : "unchanged",
+                    fields: uniqueDrift,
+                    ...(uniqueDrift.length
+                        ? { message: `run docs metadata sync for ${uniqueDrift.join(", ")}` }
+                        : {}),
+                });
+                continue;
+            }
+            const validation = validateDocsMetadataV2(expected);
+            if (!validation.valid) {
+                rows.push({
+                    repo: target.name,
+                    path,
+                    status: "invalid",
+                    fields,
+                    message: validation.issues.map((issue) => `${issue.field}: ${issue.message}`).join("; "),
+                });
+                continue;
+            }
+            if (fields.length === 0) {
+                rows.push({ repo: target.name, path, status: "unchanged", fields: [] });
+                continue;
+            }
+            writeFileSync(full, serialize(expected, current.body), "utf8");
+            rows.push({ repo: target.name, path, status: "updated", fields: [...new Set(fields)] });
+        }
+    }
+    return rows;
+}