harnery 0.33.0 → 0.34.0

package/src/commands/claude-desktop.ts

@@ -1,16 +1,12 @@
 import type { Command } from "commander";
 import type { EmitContext, HarneryProgramContext } from "../commander.ts";
-import { monorepoRoot } from "../core/agents/index.ts";
 import {
   applyMirror,
-  applyTidy,
   type DesktopAccount,
   findDesktopDataDirs,
   listAccounts,
   planMirror,
-  planTidy,
   readCliAccount,
-  readDesktopLifecycleIndex,
 } from "../lib/claude-desktop.ts";
 
 /**
@@ -31,11 +27,11 @@ import {
 export function registerClaudeDesktopCommand(
   program: Command,
   emit: EmitContext,
-  context?: HarneryProgramContext,
+  _context?: HarneryProgramContext,
 ): void {
   const cmd = program
     .command("claude-desktop")
-    .description("Claude desktop-app session index: list, mirror, and archive completed sessions")
+    .description("Claude desktop-app session index: list and mirror sessions across accounts")
     .action(() => {
       const dirs = requireDataDirs(emit, undefined);
       for (const dir of dirs) {
@@ -190,101 +186,6 @@ export function registerClaudeDesktopCommand(
         }
       },
     );
-
-  cmd
-    .command("tidy")
-    .description(
-      "Archive desktop sidebar entries whose mapped Harnery lifecycle is done. " +
-        "Dry-run by default; --yes applies atomic entry updates.",
-    )
-    .option("--data-dir <path>", "Explicit desktop-app data directory")
-    .option(
-      "--account <uuid-prefix>",
-      "Only entries under accounts matching this UUID prefix (repeatable)",
-      collect,
-      [] as string[],
-    )
-    .option(
-      "--include-legacy-prefix",
-      "Also archive unmatched historical entries whose title starts with [DONE]",
-    )
-    .option("--yes", "Apply the archive plan (default is dry-run)")
-    .action(
-      async (opts: {
-        dataDir?: string;
-        account: string[];
-        includeLegacyPrefix?: boolean;
-        yes?: boolean;
-      }) => {
-        const dirs = requireDataDirs(emit, opts.dataDir);
-        const coordRoot =
-          context?.resolveCoordRoot?.() ?? context?.repoRoot ?? monorepoRoot() ?? process.cwd();
-        const lifecycle = await readDesktopLifecycleIndex(coordRoot);
-
-        for (const dir of dirs) {
-          const plan = planTidy(listAccounts(dir), lifecycle, {
-            accounts: opts.account,
-            includeLegacyPrefix: opts.includeLegacyPrefix,
-          });
-          const planned = plan.actions.map((action) => ({
-            account_uuid: action.entry.accountUuid,
-            cli_session_id: action.entry.cliSessionId,
-            title: action.entry.title,
-            source: action.source,
-            lifecycle_updated_at: action.lifecycle?.updatedAt ?? null,
-            file: action.entry.file,
-          }));
-          const skipped = plan.skipped
-            .map((skip) => ({
-              account_uuid: skip.entry.accountUuid,
-              cli_session_id: skip.entry.cliSessionId,
-              title: skip.entry.title,
-              reason: skip.reason,
-              lifecycle: skip.lifecycle?.state ?? null,
-            }))
-            .filter((skip) => skip.reason !== "already_archived");
-          const skippedByReason = Object.fromEntries(
-            [
-              "already_archived",
-              "blocked_title",
-              "lifecycle_active",
-              "lifecycle_blocked",
-              "unmatched",
-            ].map((reason) => [
-              reason,
-              plan.skipped.filter((skip) => skip.reason === reason).length,
-            ]),
-          );
-
-          if (!opts.yes) {
-            emit.data({
-              data_dir: dir,
-              dry_run: true,
-              planned,
-              skipped,
-              skipped_by_reason: skippedByReason,
-              hint: plan.actions.length > 0 ? "re-run with --yes to archive" : "nothing to archive",
-            });
-            continue;
-          }
-
-          const result = applyTidy(plan);
-          emit.data({
-            data_dir: dir,
-            dry_run: false,
-            archived: result.archived,
-            already_archived: result.alreadyArchived,
-            planned,
-            skipped,
-            skipped_by_reason: skippedByReason,
-            hint:
-              result.archived > 0
-                ? "fully quit the Claude desktop app (tray icon, not the X) and relaunch to refresh the sidebar"
-                : "nothing to archive",
-          });
-        }
-      },
-    );
 }
 
 function collect(value: string, previous: string[]): string[] {

package/src/commands/context.ts

@@ -112,10 +112,6 @@ function renderSelf(s: NonNullable<ContextReport["self"]>): string[] {
     `  agent-${s.name ?? "?"}  (${formatAge(s.session_age_secs)} old, owner=${s.instance_id.slice(0, 8)}…)`,
   );
   if (s.task) body.push(`  task:    "${s.task}"`);
-  if (s.last_tool) {
-    const target = s.last_tool_target ? `  ${truncate(s.last_tool_target, 80)}` : "";
-    body.push(`  last:    ${s.last_tool}${target}`);
-  }
   if (s.files_held.length > 0) {
     body.push(`  holds ${s.files_held.length} file(s):`);
     for (const f of s.files_held.slice(0, 5)) body.push(`    ${f}`);
@@ -175,8 +171,7 @@ function renderPeers(p: NonNullable<ContextReport["peers"]>): string[] {
   const lines = p.rows.map((peer) => {
     const taskBit = peer.task ? ` "${truncate(peer.task, 40)}"` : "";
     const filesBit = peer.files > 0 ? `${peer.files}f` : "0f";
-    const lastBit = peer.last_tool ? `, last: ${peer.last_tool}` : "";
-    return `  agent-${peer.name.padEnd(12)}${taskBit}  (${peer.age_min}m old, ${filesBit}${lastBit})`;
+    return `  agent-${peer.name.padEnd(12)}${taskBit}  (${peer.age_min}m old, ${filesBit})`;
   });
   return section("peers", lines);
 }

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

@@ -434,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",
   };
 }
 
@@ -472,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(", ")})`);
     }