harnery 0.32.0 → 0.34.0

package/src/commands/decision.ts

@@ -1,13 +1,8 @@
 import { existsSync, readFileSync } from "node:fs";
 import type { Command } from "commander";
 import type { EmitContext } from "../commander.ts";
-import {
-  emitCanonical,
-  monorepoRoot,
-  normalizeAdapter,
-  readHeartbeat,
-  resolveOwner,
-} from "../core/agents/index.ts";
+import { emitEventV3, monorepoRoot, normalizeAdapter, resolveOwner } from "../core/agents/index.ts";
+import { readLiveCoordinationRow } from "../core/agents/state/live-coordination-view.ts";
 import { resolveBinName } from "../core/config.ts";
 import {
   archiveDecision,
@@ -79,7 +74,7 @@ export function registerDecisionCommand(program: Command, emitParam: EmitContext
         brief = readFileSync(opts.brief, "utf8");
       }
       const owner = resolveOwner();
-      const hb = owner ? readHeartbeat(owner) : null;
+      const hb = owner ? readLiveCoordinationRow(coordRoot, owner) : null;
       const r = fileDecision(coordRoot, {
         question: question.join(" "),
         tier,
@@ -91,11 +86,7 @@ export function registerDecisionCommand(program: Command, emitParam: EmitContext
         filedById: owner ?? undefined,
       });
       if (!r.ok) return fail("file_failed", r.reason);
-      emitDecisionEvent("decision.filed", {
-        decision_id: r.manifest!.decision_id,
-        tier,
-        stakes,
-      });
+      emitDecisionEvent("filed", r.manifest!);
       emit.data(r.manifest);
     });
 
@@ -214,7 +205,8 @@ export function registerDecisionCommand(program: Command, emitParam: EmitContext
     .action((id: string, opts: ResolveOpts) => {
       const coordRoot = coordRootOrExit();
       const owner = resolveOwner();
-      const resolvedBy = opts.resolvedBy ?? (owner ? readHeartbeat(owner)?.name : undefined);
+      const resolvedBy =
+        opts.resolvedBy ?? (owner ? readLiveCoordinationRow(coordRoot, owner)?.name : undefined);
       if (!resolvedBy) {
         return fail("no_resolver", "pass --resolved-by (no agent session to infer it from)");
       }
@@ -228,12 +220,7 @@ export function registerDecisionCommand(program: Command, emitParam: EmitContext
         resolved_by: resolvedBy,
       });
       if (!r.ok) return fail("resolve_failed", r.reason);
-      emitDecisionEvent("decision.resolved", {
-        decision_id: id,
-        tier: r.manifest!.tier,
-        stakes: r.manifest!.stakes,
-        confidence: opts.confidence ?? null,
-      });
+      emitDecisionEvent("resolved", r.manifest!);
       emit.data(r.manifest);
     });
 
@@ -259,11 +246,7 @@ export function registerDecisionCommand(program: Command, emitParam: EmitContext
         note: opts.note,
       });
       if (!r.ok) return fail("review_failed", r.reason);
-      emitDecisionEvent("decision.reviewed", {
-        decision_id: id,
-        verdict: opts.verdict,
-        tier: r.manifest!.tier,
-      });
+      emitDecisionEvent("reviewed", r.manifest!);
       emit.data(r.manifest);
     });
 
@@ -300,11 +283,7 @@ export function registerDecisionCommand(program: Command, emitParam: EmitContext
       const coordRoot = coordRootOrExit();
       const r = archiveDecision(coordRoot, id, opts.graduatedTo);
       if (!r.ok) return fail("archive_failed", r.reason);
-      emitDecisionEvent("decision.archived", {
-        decision_id: id,
-        tier: r.manifest!.tier,
-        graduated_to: opts.graduatedTo ?? null,
-      });
+      emitDecisionEvent("archived", r.manifest!);
       emit.data(r.manifest);
     });
 
@@ -320,7 +299,7 @@ export function registerDecisionCommand(program: Command, emitParam: EmitContext
       const coordRoot = coordRootOrExit();
       const r = reopenDecision(coordRoot, id);
       if (!r.ok) return fail("reopen_failed", r.reason);
-      emitDecisionEvent("decision.reopened", { decision_id: id, tier: r.manifest!.tier });
+      emitDecisionEvent("reviewed", r.manifest!, "archived");
       emit.data(r.manifest);
     });
 
@@ -333,10 +312,7 @@ export function registerDecisionCommand(program: Command, emitParam: EmitContext
       const coordRoot = coordRootOrExit();
       const r = supersedeDecision(coordRoot, id, opts.by);
       if (!r.ok) return fail("supersede_failed", r.reason);
-      emitDecisionEvent("decision.superseded", {
-        decision_id: id,
-        superseded_by: opts.by ?? null,
-      });
+      emitDecisionEvent("superseded", r.manifest!);
       emit.data(r.manifest);
     });
 
@@ -349,10 +325,7 @@ export function registerDecisionCommand(program: Command, emitParam: EmitContext
       const coordRoot = coordRootOrExit();
       const r = wontfixDecision(coordRoot, id, opts.reason);
       if (!r.ok) return fail("wontfix_failed", r.reason);
-      emitDecisionEvent("decision.wontfix", {
-        decision_id: id,
-        reason: opts.reason ?? null,
-      });
+      emitDecisionEvent("wontfix", r.manifest!);
       emit.data(r.manifest);
     });
 }
@@ -458,15 +431,25 @@ function summarize(m: DecisionManifest): Record<string, unknown> {
  * session to attribute it to (operator-side filing). Powers the docket metrics
  * without new telemetry plumbing.
  */
-function emitDecisionEvent(type: string, data: Record<string, unknown>): void {
+function emitDecisionEvent(
+  newState: string,
+  manifest: DecisionManifest,
+  priorState?: string,
+): void {
   const owner = resolveOwner();
   if (!owner) return;
-  const hb = readHeartbeat(owner);
-  emitCanonical({
-    type,
+  const root = monorepoRoot();
+  const hb = root ? readLiveCoordinationRow(root, owner) : null;
+  emitEventV3({
     owner,
     session: hb?.session_id ?? owner,
     adapter: normalizeAdapter(hb?.platform),
-    data,
+    observation: {
+      event_type: "decision.state_changed",
+      decision_id: manifest.decision_id,
+      ...(priorState ? { prior_state: priorState } : {}),
+      new_state: newState,
+      record: manifest,
+    },
   });
 }

package/src/commands/docs.ts

@@ -1,14 +1,13 @@
 import type { Command } from "commander";
 import type { EmitContext, HarneryProgramContext } from "../commander.ts";
 import { initDocsContext as initDocs, scanDocs } from "../lib/docs.ts";
-import {
-  initDocsMigrationContext,
-  runFrontmatterMigration,
-} from "../lib/docs-frontmatter-migrate.ts";
 import { initDocsContext as initDocsIndex, runIndex } from "../lib/docs-index.ts";
 import { initDocsContext as initDocsLinks, runLinks } from "../lib/docs-links.ts";
 import { initDocsContext as initDocsLint, runLint } from "../lib/docs-lint.ts";
 import { readDocsMetadata, readDocsMetadataKey } from "../lib/docs-meta.ts";
+import { initDocsMetadataAuditContext, runDocsMetadataAudit } from "../lib/docs-metadata-audit.ts";
+import { initDocsMetadataSyncContext, runDocsMetadataSync } from "../lib/docs-metadata-sync.ts";
+import { createDocsFile } from "../lib/docs-new.ts";
 import {
   countColdHandoffs,
   initDocsContext as initDocsSweep,
@@ -21,7 +20,6 @@ function ensureContext(context: HarneryProgramContext | undefined): void {
   }
   const opts = { repoRoot: context.repoRoot, submodules: context.submodules };
   initDocs(opts);
-  initDocsMigrationContext(opts);
   initDocsIndex(opts);
   initDocsLint({
     ...opts,
@@ -29,6 +27,8 @@ function ensureContext(context: HarneryProgramContext | undefined): void {
     docsRootAllowlist: context.docsRootAllowlist,
   });
   initDocsLinks({ ...opts, extraExcludedPrefixes: context.extraDocsExcludedPrefixes });
+  initDocsMetadataAuditContext(opts);
+  initDocsMetadataSyncContext(opts);
   initDocsSweep(opts);
 }
 
@@ -84,21 +84,109 @@ export function registerDocsCommand(
       }
     });
 
-  docs
-    .command("frontmatter-migrate")
-    .description("Convert lifecycle docs from bold metadata headers to YAML frontmatter")
+  const metadata = docs
+    .command("metadata")
+    .description("Validate and maintain the versioned markdown metadata contract");
+
+  metadata
+    .command("validate")
+    .description("Validate every managed Markdown file against harnery-doc/v2")
     .option("--repo <name>", "Limit to one submodule or '.' for parent")
-    .option("--yes", "Apply changes; without this flag the command is a dry-run")
-    .action(async (opts: { repo?: string; yes?: boolean }) => {
+    .action(async (opts: { repo?: string }) => {
       try {
         ensureContext(context);
-        handleFrontmatterMigration(opts);
+        const rows = await runDocsMetadataAudit(opts);
+        const errors = rows
+          .flatMap((row) => row.issues)
+          .filter((issue) => issue.severity === "error");
+        const warnings = rows
+          .flatMap((row) => row.issues)
+          .filter((issue) => issue.severity === "warning");
+        emit.data({
+          repo: opts.repo ?? null,
+          counts: {
+            files: rows.length,
+            valid: rows.filter((row) => row.state === "valid").length,
+            invalid: rows.filter((row) => row.state === "invalid").length,
+            legacy: rows.filter((row) => row.state === "legacy").length,
+            missing: rows.filter((row) => row.state === "missing").length,
+            errors: errors.length,
+            warnings: warnings.length,
+          },
+          rows,
+        });
+        if (errors.length > 0) emit.setExitCode(1);
       } catch (err: unknown) {
         const msg = err instanceof Error ? err.message : String(err);
         emit.error({ code: "docs_error", message: msg });
       }
     });
 
+  metadata
+    .command("sync")
+    .description("Synchronize semantic and lifecycle timestamps on staged v2 documents")
+    .argument("[files...]", "Explicit repository-relative Markdown files; defaults to staged files")
+    .option("--repo <name>", "Limit to one submodule or '.' for parent")
+    .option("--check", "Report timestamp drift without writing")
+    .option("--reviewed", "Record an explicit runbook review and move its due date")
+    .action(
+      async (files: string[], opts: { repo?: string; check?: boolean; reviewed?: boolean }) => {
+        try {
+          ensureContext(context);
+          const rows = await runDocsMetadataSync({ ...opts, files });
+          emit.data({
+            check: !!opts.check,
+            counts: {
+              files: rows.length,
+              updated: rows.filter((row) => row.status === "updated").length,
+              drift: rows.filter((row) => row.status === "drift").length,
+              invalid: rows.filter((row) => row.status === "invalid").length,
+            },
+            rows,
+          });
+          if (rows.some((row) => row.status === "drift" || row.status === "invalid")) {
+            emit.setExitCode(1);
+          }
+        } catch (err: unknown) {
+          emit.error({
+            code: "docs_error",
+            message: err instanceof Error ? err.message : String(err),
+          });
+        }
+      },
+    );
+
+  docs
+    .command("new")
+    .description("Create a document with canonical harnery-doc/v2 metadata")
+    .argument("<type>", "plan, issue, handoff, runbook, or topic")
+    .argument("<path>", "Repository-relative Markdown path")
+    .requiredOption("--summary <text>", "One-sentence document summary")
+    .requiredOption("--owner <id>", "Canonical lowercase kebab-case owner id")
+    .option("--status <status>", "Initial lifecycle status")
+    .option("--severity <severity>", "Issue severity", "medium")
+    .action(
+      (
+        type: "plan" | "issue" | "handoff" | "runbook" | "topic",
+        path: string,
+        opts: { summary: string; owner: string; status?: string; severity?: string },
+      ) => {
+        try {
+          ensureContext(context);
+          if (!["plan", "issue", "handoff", "runbook", "topic"].includes(type)) {
+            throw new Error(`unsupported document type '${type}'`);
+          }
+          const file = createDocsFile(context!.repoRoot!, { type, path, ...opts });
+          emit.data({ path: file, schema: "harnery-doc/v2", type });
+        } catch (err: unknown) {
+          emit.error({
+            code: "docs_error",
+            message: err instanceof Error ? err.message : String(err),
+          });
+        }
+      },
+    );
+
   docs
     .command("lint")
     .description(
@@ -166,7 +254,7 @@ export function registerDocsCommand(
     .command("index")
     .description("Regenerate index READMEs for docs/audits/ and docs/issues/ directories")
     .option("--dry-run", "Show what would change, don't write files")
-    .option("--repo <name>", "Limit to one submodule or '.' for parent")
+    .option("--repo <name>", "Limit to one package (in-tree or submodule) or '.' for parent")
     .action(async (opts: { dryRun?: boolean; repo?: string }) => {
       try {
         ensureContext(context);
@@ -178,27 +266,6 @@ export function registerDocsCommand(
     });
 }
 
-// --- `harn docs frontmatter-migrate` ---
-
-function handleFrontmatterMigration(opts: { repo?: string; yes?: boolean }): void {
-  const rows = runFrontmatterMigration({ repo: opts.repo, apply: !!opts.yes });
-  const counts = {
-    would_update: rows.filter((row) => row.status === "would-update").length,
-    updated: rows.filter((row) => row.status === "updated").length,
-    skipped: rows.filter((row) => row.status === "skipped").length,
-    errors: rows.filter((row) => row.status === "error").length,
-  };
-  emit.data({
-    dry_run: !opts.yes,
-    applied: !!opts.yes && counts.errors === 0,
-    aborted: !!opts.yes && counts.errors > 0,
-    repo: opts.repo ?? null,
-    counts,
-    rows,
-  });
-  if (counts.errors > 0) emit.setExitCode(1);
-}
-
 // --- `harn docs meta` ---
 
 function handleMeta(

package/src/commands/doctor.ts

@@ -21,7 +21,14 @@ import { BUILTIN_ADAPTER_IDS } from "../core/adapters/index.ts";
 import { resolveBinName, ripgrepAutoInstall } from "../core/config.ts";
 import { ADAPTER_SPECS, type AdapterId } from "../core/hooks/adapter/events.ts";
 import { loadAdapterWiring, summarizeAdapterWiring } from "../core/hooks/adapter/wiring.ts";
-import { inspectCodexWslBridge } from "../core/hooks/codex-wsl-bridge.ts";
+import {
+  type CodexHookAuthorizationResult,
+  probeCodexHookAuthorization,
+} from "../core/hooks/codex-authorization.ts";
+import {
+  type CodexWslBridgeStatus,
+  inspectCodexWslBridge,
+} from "../core/hooks/codex-wsl-bridge.ts";
 import {
   ADAPTER_BINARIES,
   ADAPTER_INSTALL_HINTS,
@@ -34,7 +41,7 @@ import { findRg, installRg, managedRgPath, rgInstallSupported } from "../lib/too
 
 type Severity = "ok" | "warn" | "fail";
 
-interface Check {
+export interface Check {
   name: string;
   severity: Severity;
   detail: string;
@@ -66,7 +73,7 @@ export function registerDoctorCommand(program: Command, emit: EmitContext): void
           emit.text(`ripgrep install failed: ${(err as Error).message}\n`);
         }
       }
-      const checks = runChecks();
+      const checks = await runChecks();
       const requiredFailed = checks.some((c) => c.severity === "fail");
 
       if (opts.json) {
@@ -99,13 +106,15 @@ export function registerDoctorCommand(program: Command, emit: EmitContext): void
     });
 }
 
-export function runChecks(): Check[] {
-  const codexWslBridge = checkCodexWslBridge();
+export async function runChecks(): Promise<Check[]> {
+  const codexWslStatus = inspectCodexWslBridge();
+  const codexWslBridge = checkCodexWslBridge(codexWslStatus);
   // Probe the adapter CLIs before the hook check runs, not in output order:
   // an unwired adapter only matters if its CLI is actually installed, and
   // probing once here keeps that join to one spawn per CLI.
   const workflow = BUILTIN_ADAPTER_IDS.map((id) => ({ id, ...checkWorkflowAdapter(id) }));
   const installed = workflow.filter((w) => w.installed).map((w) => w.id as AdapterId);
+  const codexAuthorization = await checkCodexHookAuthorization(installed, codexWslStatus);
   return [
     checkNode(),
     checkGit(),
@@ -113,6 +122,7 @@ export function runChecks(): Check[] {
     checkRipgrep(),
     checkHarneryDir(),
     checkAdapterHooks(installed),
+    ...(codexAuthorization ? [codexAuthorization] : []),
     checkGitHookRegions(),
     ...(codexWslBridge ? [codexWslBridge] : []),
     ...workflow.map((w) => w.check),
@@ -153,8 +163,7 @@ function checkGitHookRegions(): Check {
   }
 }
 
-function checkCodexWslBridge(): Check | null {
-  const status = inspectCodexWslBridge();
+function checkCodexWslBridge(status: CodexWslBridgeStatus | null): Check | null {
   if (!status) return null;
   return {
     name: "codex:WSL bridge",
@@ -166,6 +175,49 @@ function checkCodexWslBridge(): Check | null {
   };
 }
 
+export function codexAuthorizationCheck(result: CodexHookAuthorizationResult): Check {
+  const reviewHint =
+    "terminal UI: run `/hooks`; Codex Desktop: open Settings > Hooks; after approval, start a fresh task";
+  if (result.status === "runnable") {
+    return { name: "codex:hook authorization", severity: "ok", detail: result.detail };
+  }
+  if (result.status === "review_required" || result.status === "disabled") {
+    return {
+      name: "codex:hook authorization",
+      severity: "warn",
+      detail: result.detail,
+      hint: reviewHint,
+    };
+  }
+  return {
+    name: "codex:hook authorization",
+    severity: "warn",
+    detail: `authorization unverified: ${result.detail}`,
+    hint: reviewHint,
+  };
+}
+
+async function checkCodexHookAuthorization(
+  installedAdapters: AdapterId[],
+  codexWslStatus: CodexWslBridgeStatus | null,
+): Promise<Check | null> {
+  const root = findCoordProjectRoot();
+  if (!root || !summarizeAdapterWiring(root).wired.includes("codex")) return null;
+
+  if (codexWslStatus) {
+    return {
+      name: "codex:hook authorization",
+      severity: "warn",
+      detail:
+        "unverified from WSL; the Windows-native Codex runtime owns this workspace's trust state",
+      hint: "run the host's Windows bridge doctor, or open Codex Desktop Settings > Hooks; start a fresh task after approval",
+    };
+  }
+  if (!installedAdapters.includes("codex")) return null;
+
+  return codexAuthorizationCheck(await probeCodexHookAuthorization({ cwd: root }));
+}
+
 function checkRipgrep(): Check {
   const found = findRg();
   if (found) {
@@ -382,7 +434,7 @@ function checkHarneryDir(): Check {
     name: ".harnery/",
     severity: "warn",
     detail: "no .harnery/ found above cwd",
-    hint: "create one with `mkdir -p .harnery/active` from your monorepo root",
+    hint: "initialize the project with `harn init` from the repository root",
   };
 }
 
@@ -420,6 +472,19 @@ function checkAdapterHooks(installedAdapters: AdapterId[] = []): Check {
       bits.push(`${d.missing.length} missing (${d.missing.map((m) => m.subcommand).join(", ")})`);
     }
     if (d.orphans.length > 0) bits.push(`${d.orphans.length} orphaned (${d.orphans.join(", ")})`);
+    if (d.duplicates.length > 0) {
+      bits.push(
+        `${d.duplicates.length} duplicated (${d.duplicates.map((e) => e.settingsKey).join(", ")})`,
+      );
+    }
+    if (d.misplaced.length > 0) {
+      bits.push(
+        `${d.misplaced.length} misplaced (${d.misplaced.map((e) => e.subcommand).join(", ")})`,
+      );
+    }
+    if (d.stale.length > 0) {
+      bits.push(`${d.stale.length} stale (${d.stale.map((e) => e.settingsKey).join(", ")})`);
+    }
     if (d.invalidTopLevelKeys.length > 0) {
       bits.push(`invalid fields (${d.invalidTopLevelKeys.join(", ")})`);
     }