harnery 0.32.0 → 0.34.0

package/dist/lib/council/index.js

@@ -9,6 +9,7 @@ import { createHash, randomBytes } from "node:crypto";
 import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
 import { basename, resolve } from "node:path";
 import { monorepoRoot } from "../../core/agents/index.js";
+import { readLiveCoordinationRows } from "../../core/agents/state/live-coordination-view.js";
 import { resolveBinName } from "../../core/config.js";
 import { ensureIdentity, lookupById as lookupIdentityById } from "../identities/index.js";
 export const COUNCIL_SCHEMA_VERSION = 2;
@@ -176,7 +177,7 @@ export function setCouncilSteward(councilId, steward) {
  * next-app's same-named constant. */
 const KNOWN_AGENT_STALE_WINDOW_MS = 30 * 24 * 60 * 60 * 1000;
 /**
- * Active heartbeats + recently-archived journals, deduped by name.
+ * Active V3 generations + recently-archived journals, deduped by name.
  * Used by `agents council set-steward` to refuse arbitrary names;
  * pass `--allow-unknown` to bypass when bootstrapping a new agent.
  */
@@ -184,27 +185,15 @@ export function listKnownAgents() {
     const root = monorepoRoot();
     if (!root)
         return [];
-    const activeDir = resolve(root, ".harnery", "active");
     const archiveDir = resolve(root, ".harnery", "journal", "archived");
     const byName = new Map();
-    if (existsSync(activeDir)) {
-        for (const f of readdirSync(activeDir)) {
-            if (!f.endsWith(".json"))
-                continue;
-            try {
-                const hb = JSON.parse(readFileSync(resolve(activeDir, f), "utf8"));
-                if (!hb.name)
-                    continue;
-                const name = hb.name.startsWith("agent-") ? hb.name : `agent-${hb.name}`;
-                const last_seen = hb.last_heartbeat ?? new Date().toISOString();
-                const existing = byName.get(name);
-                if (existing?.state !== "active") {
-                    byName.set(name, { name, state: "active", last_seen });
-                }
-            }
-            catch {
-                /* skip unreadable */
-            }
+    for (const row of readLiveCoordinationRows(root)) {
+        if (!row.name)
+            continue;
+        const name = row.name.startsWith("agent-") ? row.name : `agent-${row.name}`;
+        const existing = byName.get(name);
+        if (existing?.state !== "active") {
+            byName.set(name, { name, state: "active", last_seen: row.last_heartbeat });
         }
     }
     const cutoff = Date.now() - KNOWN_AGENT_STALE_WINDOW_MS;

package/dist/lib/docs-frontmatter.d.ts

@@ -19,12 +19,7 @@ export type DocKind = "plan" | "issue" | "handoff";
  * stripped from `body`, so status readers do not need try/catch.
  */
 export declare function parseFrontmatter(text: string): ParsedFrontmatter;
-/**
- * Normalize a raw status token to the canonical enum for its kind.
- * Returns null when the token can't be mapped (caller may fail loud).
- */
-export declare function normalizeStatus(raw: string, kind?: DocKind): string | null;
-/** Read and normalize a doc's YAML lifecycle status, or null when absent/invalid. */
+/** Read a canonical v2 lifecycle status, or null when absent or invalid. */
 export declare function readDocStatus(filePath: string, kind?: DocKind): string | null;
 /** Same as {@link readDocStatus} but from an in-memory string (testable). */
 export declare function readDocStatusFromText(content: string, kind?: DocKind): string | null;

package/dist/lib/docs-frontmatter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"docs-frontmatter.d.ts","sourceRoot":"","sources":["../../src/lib/docs-frontmatter.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AAEH,MAAM,WAAW,iBAAiB;IAChC,uEAAuE;IACvE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;IACb,oEAAoE;IACpE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CACpB;AAED,+CAA+C;AAC/C,MAAM,MAAM,OAAO,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;AAKnD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,CAgBhE;AA+DD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAW1E;AAED,qFAAqF;AACrF,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAQ7E;AAED,6EAA6E;AAC7E,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAOpF;AAED,4EAA4E;AAC5E,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAGtD"}
+{"version":3,"file":"docs-frontmatter.d.ts","sourceRoot":"","sources":["../../src/lib/docs-frontmatter.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AAEH,MAAM,WAAW,iBAAiB;IAChC,uEAAuE;IACvE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;IACb,oEAAoE;IACpE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CACpB;AAED,+CAA+C;AAC/C,MAAM,MAAM,OAAO,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;AAKnD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,CAgBhE;AAOD,4EAA4E;AAC5E,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAQ7E;AAED,6EAA6E;AAC7E,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CASpF;AAED,4EAA4E;AAC5E,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAGtD"}

package/dist/lib/docs-frontmatter.js

@@ -26,84 +26,12 @@ export function parseFrontmatter(text) {
     }
     return { data, body: text.slice(m[0].length), raw: m[1] };
 }
-/**
- * Kind-independent token normalization (spacing / casing / punctuation
- * variants). Kind-specific collapses (done -> shipped vs resolved) are applied
- * in `normalizeStatus`.
- */
-const GENERIC_NORMALIZE = {
-    in_progress: "in-progress",
-    inprogress: "in-progress",
-    "in progress": "in-progress",
-    "in-progress": "in-progress",
-    wip: "in-progress",
-    "wont-fix": "wontfix",
-    wontfix: "wontfix",
-    proposed: "proposed",
-    abandoned: "abandoned",
-    open: "open",
-    resolved: "resolved",
-    shipped: "shipped",
-};
-// "done"-family tokens collapse to different canonical values per kind.
-const DONE_FAMILY = new Set(["done", "complete", "completed", "finished"]);
-const KIND_NORMALIZE = {
-    plan: {
-        planning: "proposed",
-        draft: "proposed",
-        approved: "proposed",
-        plan: "proposed",
-        open: "proposed",
-        deferred: "proposed",
-        implemented: "shipped",
-        resolved: "shipped",
-        fixed: "shipped",
-        archived: "shipped",
-        shelved: "abandoned",
-    },
-    issue: {
-        "in progress": "open",
-        in_progress: "open",
-        "in-progress": "open",
-        blocked: "open",
-        mitigated: "open",
-        fixed: "resolved",
-        shipped: "resolved",
-    },
-    handoff: {
-        "in progress": "open",
-        in_progress: "open",
-        "in-progress": "open",
-        blocked: "open",
-        fixed: "resolved",
-        shipped: "resolved",
-    },
-};
 const ALLOWED_BY_KIND = {
     plan: new Set(["proposed", "in-progress", "shipped", "abandoned"]),
     issue: new Set(["open", "resolved", "wontfix"]),
     handoff: new Set(["open", "resolved", "abandoned"]),
 };
-const ALL_CANONICAL = new Set(Object.values(ALLOWED_BY_KIND).flatMap((values) => [...values]));
-/**
- * Normalize a raw status token to the canonical enum for its kind.
- * Returns null when the token can't be mapped (caller may fail loud).
- */
-export function normalizeStatus(raw, kind) {
-    const t = raw.trim().toLowerCase();
-    if (!t)
-        return null;
-    if (DONE_FAMILY.has(t)) {
-        // plans ship; issues/handoffs resolve. Default to "shipped" when unknown.
-        return kind === "issue" || kind === "handoff" ? "resolved" : "shipped";
-    }
-    const normalized = (kind ? KIND_NORMALIZE[kind][t] : undefined) ?? GENERIC_NORMALIZE[t];
-    if (!normalized)
-        return null;
-    const allowed = kind ? ALLOWED_BY_KIND[kind] : ALL_CANONICAL;
-    return allowed.has(normalized) ? normalized : null;
-}
-/** Read and normalize a doc's YAML lifecycle status, or null when absent/invalid. */
+/** Read a canonical v2 lifecycle status, or null when absent or invalid. */
 export function readDocStatus(filePath, kind) {
     let content;
     try {
@@ -117,11 +45,17 @@ export function readDocStatus(filePath, kind) {
 /** Same as {@link readDocStatus} but from an in-memory string (testable). */
 export function readDocStatusFromText(content, kind) {
     const { data } = parseFrontmatter(content);
-    const yamlStatus = data.status;
-    if (typeof yamlStatus === "string" && yamlStatus.trim()) {
-        return normalizeStatus(yamlStatus, kind);
-    }
-    return null;
+    if (data.schema !== "harnery-doc/v2")
+        return null;
+    if (kind && data.type !== kind)
+        return null;
+    if (typeof data.status !== "string")
+        return null;
+    if (kind)
+        return ALLOWED_BY_KIND[kind].has(data.status) ? data.status : null;
+    return Object.values(ALLOWED_BY_KIND).some((allowed) => allowed.has(data.status))
+        ? data.status
+        : null;
 }
 /** Whether a doc carries a non-empty status in leading YAML frontmatter. */
 export function hasYamlStatus(content) {

package/dist/lib/docs-index.d.ts

@@ -7,6 +7,10 @@ export declare function initDocsContext(opts: {
  * Idempotent: safe to run on every commit. Reads the first ~30 lines of
  * each dated file to extract title and (for issues) status.
  *
+ * Targets: the host root, every initialized git submodule, and first-level
+ * in-tree packages that keep `docs/audits` or `docs/issues` without being
+ * git submodules. Marker rules are unchanged.
+ *
  * Preserves hand-written preambles. The command updates only the section
  * between `<!-- BEGIN INDEX -->` and `<!-- END INDEX -->` markers. If a
  * README exists without markers, the command refuses to overwrite it and
@@ -25,5 +29,10 @@ export interface IndexResult {
     after: string;
 }
 export declare function extractStatus(content: string): string | undefined;
+/** Root + initialized submodules + first-level in-tree packages with docs indexes. */
+export declare function collectIndexTargets(): {
+    name: string;
+    path: string;
+}[];
 export declare function runIndex(opts: IndexOpts): Promise<IndexResult[]>;
 //# sourceMappingURL=docs-index.d.ts.map

package/dist/lib/docs-index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"docs-index.d.ts","sourceRoot":"","sources":["../../src/lib/docs-index.ts"],"names":[],"mappings":"AASA,wBAAgB,eAAe,CAAC,IAAI,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAAG,IAAI,CAG/F;AAeD;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,SAAS;IACxB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG,SAAS,GAAG,eAAe,GAAG,SAAS,CAAC;AAEhF,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,WAAW,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAkBD,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEjE;AAgGD,wBAAsB,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CA+CtE"}
+{"version":3,"file":"docs-index.d.ts","sourceRoot":"","sources":["../../src/lib/docs-index.ts"],"names":[],"mappings":"AASA,wBAAgB,eAAe,CAAC,IAAI,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAAG,IAAI,CAG/F;AAeD;;;;;;;;;;;;;;GAcG;AAEH,MAAM,WAAW,SAAS;IACxB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG,SAAS,GAAG,eAAe,GAAG,SAAS,CAAC;AAEhF,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,WAAW,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAkBD,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEjE;AAsGD,sFAAsF;AACtF,wBAAgB,mBAAmB,IAAI;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EAAE,CAqBtE;AAED,wBAAsB,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CA2CtE"}

package/dist/lib/docs-index.js

@@ -122,13 +122,42 @@ function hasMarkers(existing) {
 function buildNewReadme(kind, body) {
     return `${defaultPreamble(kind)}\n${BEGIN_MARKER}\n${body}${END_MARKER}\n`;
 }
-export async function runIndex(opts) {
-    const targets = [{ name: "(root)", path: REPO_ROOT }];
+const SKIP_NESTED_DIR_NAMES = new Set(["node_modules", "dist", "target"]);
+function hasIndexableDocs(path) {
+    return existsSync(join(path, "docs", "audits")) || existsSync(join(path, "docs", "issues"));
+}
+/** Root + initialized submodules + first-level in-tree packages with docs indexes. */
+export function collectIndexTargets() {
+    const byPath = new Map();
+    const add = (name, path) => {
+        byPath.set(path, { name, path });
+    };
+    add("(root)", REPO_ROOT);
     for (const name of SUBMODULES) {
         if (!isSubmoduleInitialized(name))
             continue;
-        targets.push({ name, path: submodulePath(name) });
+        add(name, submodulePath(name));
+    }
+    if (!existsSync(REPO_ROOT))
+        return [...byPath.values()];
+    for (const ent of readdirSync(REPO_ROOT, { withFileTypes: true })) {
+        if (!ent.isDirectory() && !ent.isSymbolicLink())
+            continue;
+        if (ent.name.startsWith("."))
+            continue;
+        if (SKIP_NESTED_DIR_NAMES.has(ent.name))
+            continue;
+        if (isSubmoduleInitialized(ent.name))
+            continue;
+        const child = join(REPO_ROOT, ent.name);
+        if (!hasIndexableDocs(child))
+            continue;
+        add(ent.name, child);
     }
+    return [...byPath.values()];
+}
+export async function runIndex(opts) {
+    const targets = collectIndexTargets();
     const filter = opts.repo === "." ? "(root)" : opts.repo;
     const filtered = filter ? targets.filter((t) => t.name === filter) : targets;
     const results = [];

package/dist/lib/docs-lint.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"docs-lint.d.ts","sourceRoot":"","sources":["../../src/lib/docs-lint.ts"],"names":[],"mappings":"AAcA,wBAAgB,eAAe,CAAC,IAAI,EAAE;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,qBAAqB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC,GAAG,IAAI,CAKP;AAaD;;;;;;GAMG;AAEH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,SAAS,CAAC;AAE3C,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,QAAQ,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AA0HD,kFAAkF;AAClF,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAMrD;AAsQD,wBAAsB,OAAO,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAqBlE"}
+{"version":3,"file":"docs-lint.d.ts","sourceRoot":"","sources":["../../src/lib/docs-lint.ts"],"names":[],"mappings":"AAeA,wBAAgB,eAAe,CAAC,IAAI,EAAE;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,qBAAqB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC,GAAG,IAAI,CAMP;AAaD;;;;;;GAMG;AAEH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,SAAS,CAAC;AAE3C,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,QAAQ,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AA0HD,kFAAkF;AAClF,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAMrD;AA0OD,wBAAsB,OAAO,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAiClE"}

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"}