@a5c-ai/git-a5c 1.0.2

package/dist/run.js

@@ -0,0 +1,83 @@
+import { detectRepoRoot } from "./git.js";
+import { parseArgs } from "./args.js";
+import { createLogger, loadSnapshot, openRepo, parseLogLevel } from "@a5cforge/sdk";
+import { handleHelp } from "./commands/help.js";
+import { handleWebhook } from "./commands/webhook.js";
+import { handleStatus } from "./commands/status.js";
+import { handleIssue } from "./commands/issue.js";
+import { handlePr } from "./commands/pr.js";
+import { handleBlock } from "./commands/block.js";
+import { handleGate } from "./commands/gate.js";
+import { handleAgent } from "./commands/agent.js";
+import { handleOps } from "./commands/ops.js";
+import { handleHooks } from "./commands/hooks.js";
+import { handleVerify } from "./commands/verify.js";
+import { handleJournal } from "./commands/journal.js";
+function writeLine(write, s = "") {
+    write(s + "\n");
+}
+function nowMs() {
+    // Test hook for deterministic journal/active: set A5C_NOW_ISO=...
+    const iso = process.env.A5C_NOW_ISO;
+    if (iso) {
+        const ms = Date.parse(iso);
+        if (Number.isFinite(ms))
+            return ms;
+    }
+    return Date.now();
+}
+export async function runCli(argv, opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const out = opts.stdout ?? ((s) => process.stdout.write(s));
+    const err = opts.stderr ?? ((s) => process.stderr.write(s));
+    const log = createLogger({ base: { component: "cli" }, level: parseLogLevel(process.env.A5C_LOG_LEVEL ?? "silent") });
+    const { flags, positionals } = parseArgs(argv);
+    const cmd = positionals[0] ?? "help";
+    let repoRoot;
+    try {
+        repoRoot = typeof flags.repo === "string" ? flags.repo : await detectRepoRoot(cwd);
+    }
+    catch {
+        writeLine(err, "not a git repository (use --repo <path>)");
+        return 2;
+    }
+    const treeish = typeof flags.treeish === "string" ? flags.treeish : "HEAD";
+    log.debug("start", { cmd, treeish, repoRoot });
+    const repo = await openRepo(repoRoot);
+    const snap = await loadSnapshot({ git: repo.git, treeish, inboxRefs: flags.inboxRefs });
+    const baseArgs = {
+        repoRoot,
+        treeish,
+        flags,
+        positionals,
+        repo,
+        snap,
+        nowMs,
+        io: { out, err, writeLine }
+    };
+    const handlers = [
+        () => handleHelp(baseArgs),
+        () => handleWebhook(baseArgs),
+        () => handleStatus(baseArgs),
+        () => handleIssue(baseArgs),
+        () => handlePr(baseArgs),
+        () => handleBlock(baseArgs),
+        () => handleGate(baseArgs),
+        () => handleAgent(baseArgs),
+        () => handleOps(baseArgs),
+        () => handleHooks(baseArgs),
+        () => handleVerify(baseArgs),
+        () => handleJournal(baseArgs)
+    ];
+    for (const h of handlers) {
+        const r = await h();
+        if (r !== undefined) {
+            log.debug("done", { code: r });
+            return r;
+        }
+    }
+    writeLine(err, `unknown command: ${cmd}`);
+    log.warn("unknown_command", { cmd });
+    return 2;
+}
+//# sourceMappingURL=run.js.map

package/dist/run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":"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"}

package/dist/time.d.ts

@@ -0,0 +1,2 @@
+export declare function parseSinceToEpochMs(since: string, nowMs: number): number;
+//# sourceMappingURL=time.d.ts.map

package/dist/time.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"time.d.ts","sourceRoot":"","sources":["../src/time.ts"],"names":[],"mappings":"AAAA,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAaxE"}

package/dist/time.js

@@ -0,0 +1,16 @@
+export function parseSinceToEpochMs(since, nowMs) {
+    // Accept:
+    // - ISO timestamp
+    // - durations like 2h, 15m, 30s, 7d
+    const iso = Date.parse(since);
+    if (Number.isFinite(iso))
+        return iso;
+    const m = /^(\d+)(s|m|h|d)$/.exec(since.trim());
+    if (!m)
+        throw new Error(`Invalid --since: ${since}`);
+    const n = Number(m[1]);
+    const unit = m[2];
+    const mult = unit === "s" ? 1000 : unit === "m" ? 60_000 : unit === "h" ? 3_600_000 : 86_400_000;
+    return nowMs - n * mult;
+}
+//# sourceMappingURL=time.js.map

package/dist/time.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"time.js","sourceRoot":"","sources":["../src/time.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,mBAAmB,CAAC,KAAa,EAAE,KAAa;IAC9D,UAAU;IACV,kBAAkB;IAClB,oCAAoC;IACpC,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC9B,IAAI,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,GAAG,CAAC;IAErC,MAAM,CAAC,GAAG,kBAAkB,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;IAChD,IAAI,CAAC,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,oBAAoB,KAAK,EAAE,CAAC,CAAC;IACrD,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACvB,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IAClB,MAAM,IAAI,GAAG,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC;IACjG,OAAO,KAAK,GAAG,CAAC,GAAG,IAAI,CAAC;AAC1B,CAAC"}

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@a5c-ai/git-a5c",
+  "version": "1.0.2",
+  "type": "module",
+  "bin": {
+    "git-a5c": "./dist/bin/git-a5c.js"
+  },
+  "dependencies": {
+    "@a5cforge/sdk": "0.1.0"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^2.1.8",
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.8"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage"
+  }
+}

package/src/args.ts

@@ -0,0 +1,87 @@
+export type ParsedArgs = {
+  flags: {
+    repo?: string;
+    treeish?: string;
+    json?: boolean;
+    inboxRefs?: string[];
+    since?: string;
+    limit?: number;
+    types?: string[];
+    entity?: string;
+    active?: boolean;
+    stageOnly?: boolean;
+    commit?: boolean;
+    message?: string;
+    title?: string;
+    body?: string;
+    id?: string;
+    commentId?: string;
+    reason?: string;
+    base?: string;
+    head?: string;
+    headRef?: string;
+    topic?: string;
+    by?: string;
+    op?: string;
+    agentId?: string;
+    ttlSeconds?: number;
+    task?: string;
+    env?: string;
+    rev?: string;
+    artifact?: string;
+    dispatchId?: string;
+    url?: string;
+    type?: string;
+  };
+  positionals: string[];
+};
+
+export function parseArgs(argv: string[]): ParsedArgs {
+  const args = [...argv];
+  const flags: ParsedArgs["flags"] = {};
+  const positionals: string[] = [];
+
+  while (args.length) {
+    const a = args.shift()!;
+    if (a === "--repo") flags.repo = args.shift()!;
+    else if (a === "--treeish") flags.treeish = args.shift()!;
+    else if (a === "--json") flags.json = true;
+    else if (a === "--inbox-ref") {
+      const v = args.shift()!;
+      flags.inboxRefs ??= [];
+      flags.inboxRefs.push(v);
+    } else if (a === "--since") flags.since = args.shift()!;
+    else if (a === "--limit") flags.limit = Number(args.shift()!);
+    else if (a === "--types") flags.types = args.shift()!.split(",").map((s) => s.trim()).filter(Boolean);
+    else if (a === "--entity") flags.entity = args.shift()!;
+    else if (a === "--active") flags.active = true;
+    else if (a === "--stage-only") flags.stageOnly = true;
+    else if (a === "--commit") flags.commit = true;
+    else if (a === "--message" || a === "-m") flags.message = args.shift()!;
+    else if (a === "--title") flags.title = args.shift()!;
+    else if (a === "--body") flags.body = args.shift()!;
+    else if (a === "--id") flags.id = args.shift()!;
+    else if (a === "--comment-id") flags.commentId = args.shift()!;
+    else if (a === "--reason") flags.reason = args.shift()!;
+    else if (a === "--base") flags.base = args.shift()!;
+    else if (a === "--head") flags.head = args.shift()!;
+    else if (a === "--head-ref") flags.headRef = args.shift()!;
+    else if (a === "--topic") flags.topic = args.shift()!;
+    else if (a === "--by") flags.by = args.shift()!;
+    else if (a === "--op") flags.op = args.shift()!;
+    else if (a === "--agent-id") flags.agentId = args.shift()!;
+    else if (a === "--ttl-seconds") flags.ttlSeconds = Number(args.shift()!);
+    else if (a === "--task") flags.task = args.shift()!;
+    else if (a === "--env") flags.env = args.shift()!;
+    else if (a === "--rev") flags.rev = args.shift()!;
+    else if (a === "--artifact") flags.artifact = args.shift()!;
+    else if (a === "--dispatch-id") flags.dispatchId = args.shift()!;
+    else if (a === "--url") flags.url = args.shift()!;
+    else if (a === "--type") flags.type = args.shift()!;
+    else positionals.push(a);
+  }
+
+  return { flags, positionals };
+}
+
+

package/src/bin/git-a5c.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { runCli } from "../run.js";
+
+runCli(process.argv.slice(2))
+  .then((code) => {
+    process.exitCode = code;
+  })
+  .catch((e) => {
+    // Keep output minimal and deterministic.
+    process.stderr.write(String(e?.message ?? e) + "\n");
+    process.exitCode = 1;
+  });
+
+

package/src/commands/agent.ts

@@ -0,0 +1,72 @@
+import type { CommandArgs } from "./types.js";
+import { git, gitConfigGet } from "../git.js";
+import {
+  HlcClock,
+  UlidGenerator,
+  loadHlcState,
+  saveHlcState,
+  stageFiles,
+  writeAgentHeartbeat,
+  writeAgentDispatchCreated
+} from "@a5cforge/sdk";
+
+export async function handleAgent(args: CommandArgs): Promise<number | undefined> {
+  if (args.positionals[0] !== "agent") return;
+  const sub = args.positionals[1];
+  const actor = process.env.A5C_ACTOR ?? (await gitConfigGet(args.repoRoot, "user.name")) ?? "unknown";
+  const persisted = (await loadHlcState(actor)) ?? { wallMs: 0, counter: 0 };
+  const clock = new HlcClock(persisted);
+  let nonce = 0;
+  const ctx = { repoRoot: args.repoRoot, actor, clock, nextNonce: () => String(++nonce).padStart(4, "0") };
+
+  if (sub === "heartbeat") {
+    const agentId = args.flags.agentId ?? actor;
+    const ttlSeconds = args.flags.ttlSeconds ?? 120;
+    const time = new Date(args.nowMs()).toISOString();
+    const status = args.flags.message ?? undefined;
+    const entityId = args.flags.entity;
+    const entity = entityId ? ({ type: entityId.startsWith("pr-") ? "pr" : "issue", id: entityId } as const) : undefined;
+    const res = await writeAgentHeartbeat(ctx, { agentId, ttlSeconds, status, entity, time });
+    await saveHlcState(actor, clock.now());
+    if (args.flags.stageOnly || args.flags.commit) await stageFiles(args.repoRoot, [res.path]);
+    if (args.flags.commit) {
+      const msg = args.flags.message ?? `a5c: agent heartbeat ${agentId}`;
+      await git(["-c", "user.name=a5c", "-c", "user.email=a5c@example.invalid", "commit", "-m", msg], args.repoRoot);
+    }
+    args.io.writeLine(args.io.out, res.path);
+    return 0;
+  }
+
+  if (sub === "dispatch") {
+    const entityId = args.flags.entity;
+    if (!entityId) {
+      args.io.writeLine(args.io.err, "usage: git a5c agent dispatch --entity <issueId|prKey> [--dispatch-id ...] [--task ...]");
+      return 2;
+    }
+    const dispatchId = args.flags.dispatchId ?? `d-${new UlidGenerator().generate()}`;
+    const time = new Date(args.nowMs()).toISOString();
+    const entity = { type: entityId.startsWith("pr-") ? "pr" : "issue", id: entityId } as const;
+    const agentId = args.flags.agentId ?? actor;
+    const res = await writeAgentDispatchCreated(ctx, {
+      dispatchId,
+      agentId,
+      entity,
+      task: args.flags.task,
+      params: undefined,
+      time
+    });
+    await saveHlcState(actor, clock.now());
+    if (args.flags.stageOnly || args.flags.commit) await stageFiles(args.repoRoot, [res.path]);
+    if (args.flags.commit) {
+      const msg = args.flags.message ?? `a5c: agent dispatch ${dispatchId}`;
+      await git(["-c", "user.name=a5c", "-c", "user.email=a5c@example.invalid", "commit", "-m", msg], args.repoRoot);
+    }
+    args.io.writeLine(args.io.out, res.path);
+    return 0;
+  }
+
+  args.io.writeLine(args.io.err, "usage: git a5c agent heartbeat|dispatch ...");
+  return 2;
+}
+
+

package/src/commands/block.ts

@@ -0,0 +1,34 @@
+import type { CommandArgs } from "./types.js";
+import { git, gitConfigGet } from "../git.js";
+import { HlcClock, loadHlcState, saveHlcState, stageFiles, writeDepChanged } from "@a5cforge/sdk";
+
+export async function handleBlock(args: CommandArgs): Promise<number | undefined> {
+  if (args.positionals[0] !== "block") return;
+  // git a5c block <entityId> --by <issueOrPrId> [--op add|remove]
+  const entityId = args.positionals[1];
+  const byId = args.flags.by;
+  const op = (args.flags.op as any) ?? "add";
+  if (!entityId || !byId) {
+    args.io.writeLine(args.io.err, "usage: git a5c block <entityId> --by <issue|pr> [--op add|remove]");
+    return 2;
+  }
+  const entity = { type: entityId.startsWith("pr-") ? "pr" : "issue", id: entityId } as const;
+  const by = { type: byId.startsWith("pr-") ? "pr" : "issue", id: byId } as const;
+  const actor = process.env.A5C_ACTOR ?? (await gitConfigGet(args.repoRoot, "user.name")) ?? "unknown";
+  const time = new Date(args.nowMs()).toISOString();
+  const persisted = (await loadHlcState(actor)) ?? { wallMs: 0, counter: 0 };
+  const clock = new HlcClock(persisted);
+  let nonce = 0;
+  const ctx = { repoRoot: args.repoRoot, actor, clock, nextNonce: () => String(++nonce).padStart(4, "0") };
+  const res = await writeDepChanged(ctx, { entity, op, by, note: args.flags.message as any, time });
+  await saveHlcState(actor, clock.now());
+  if (args.flags.stageOnly || args.flags.commit) await stageFiles(args.repoRoot, [res.path]);
+  if (args.flags.commit) {
+    const msg = args.flags.message ?? `a5c: dep ${op} ${entityId}`;
+    await git(["-c", "user.name=a5c", "-c", "user.email=a5c@example.invalid", "commit", "-m", msg], args.repoRoot);
+  }
+  args.io.writeLine(args.io.out, res.path);
+  return 0;
+}
+
+

package/src/commands/gate.ts

@@ -0,0 +1,32 @@
+import type { CommandArgs } from "./types.js";
+import { git, gitConfigGet } from "../git.js";
+import { HlcClock, loadHlcState, saveHlcState, stageFiles, writeGateChanged } from "@a5cforge/sdk";
+
+export async function handleGate(args: CommandArgs): Promise<number | undefined> {
+  if (args.positionals[0] !== "gate") return;
+  const sub = args.positionals[1];
+  const entityId = args.positionals[2];
+  if (!sub || !entityId) {
+    args.io.writeLine(args.io.err, "usage: git a5c gate needs-human|clear <entityId> [--topic t] [-m msg]");
+    return 2;
+  }
+  const entity = { type: entityId.startsWith("pr-") ? "pr" : "issue", id: entityId } as const;
+  const needsHuman = sub === "needs-human";
+  const actor = process.env.A5C_ACTOR ?? (await gitConfigGet(args.repoRoot, "user.name")) ?? "unknown";
+  const time = new Date(args.nowMs()).toISOString();
+  const persisted = (await loadHlcState(actor)) ?? { wallMs: 0, counter: 0 };
+  const clock = new HlcClock(persisted);
+  let nonce = 0;
+  const ctx = { repoRoot: args.repoRoot, actor, clock, nextNonce: () => String(++nonce).padStart(4, "0") };
+  const res = await writeGateChanged(ctx, { entity, needsHuman, topic: args.flags.topic, message: args.flags.message as any, time });
+  await saveHlcState(actor, clock.now());
+  if (args.flags.stageOnly || args.flags.commit) await stageFiles(args.repoRoot, [res.path]);
+  if (args.flags.commit) {
+    const msg = args.flags.message ?? `a5c: gate ${sub} ${entityId}`;
+    await git(["-c", "user.name=a5c", "-c", "user.email=a5c@example.invalid", "commit", "-m", msg], args.repoRoot);
+  }
+  args.io.writeLine(args.io.out, res.path);
+  return 0;
+}
+
+

package/src/commands/help.ts

@@ -0,0 +1,38 @@
+import type { CommandArgs } from "./types.js";
+
+export function handleHelp(args: CommandArgs): number | undefined {
+  const cmd = args.positionals[0] ?? "help";
+  if (cmd !== "help" && cmd !== "--help" && cmd !== "-h") return;
+
+  const { writeLine } = args.io;
+  const out = args.io.out;
+  writeLine(out, "git a5c <command> [--json] [--treeish <ref>] [--repo <path>] [--inbox-ref <ref>...]");
+  writeLine(out, "");
+  writeLine(out, "Commands:");
+  writeLine(out, "  status");
+  writeLine(out, "  issue list");
+  writeLine(out, "  issue show <id>");
+  writeLine(out, "  issue new --title <t> [--body <b>] [--stage-only|--commit]");
+  writeLine(out, "  issue comment <id> -m <text> [--comment-id <id>] [--stage-only|--commit]");
+  writeLine(out, "  issue edit-comment <commentId> --id <issueId> -m <text> [--stage-only|--commit]");
+  writeLine(out, "  issue redact-comment <commentId> --id <issueId> [--reason <r>] [--stage-only|--commit]");
+  writeLine(out, "  pr list");
+  writeLine(out, "  pr show <prKey>");
+  writeLine(out, "  pr propose --base <ref> --head <ref> --title <t> [--body <b>] [--stage-only|--commit]");
+  writeLine(out, "  pr request --base <ref> --title <t> [--body <b>] [--stage-only|--commit]");
+  writeLine(out, "  pr claim <prKey> --head-ref <ref> [-m <msg>] [--stage-only|--commit]");
+  writeLine(out, "  pr bind-head <prKey> --head-ref <ref> [-m <msg>] [--stage-only|--commit]");
+  writeLine(out, "  block <entityId> --by <issue|pr> [--op add|remove] [-m <note>] [--stage-only|--commit]");
+  writeLine(out, "  gate needs-human <entityId> [--topic <t>] [-m <msg>] [--stage-only|--commit]");
+  writeLine(out, "  gate clear <entityId> [-m <msg>] [--stage-only|--commit]");
+  writeLine(out, "  agent heartbeat [--agent-id <id>] [--ttl-seconds N] [--entity <id>] [-m <status>] [--stage-only|--commit]");
+  writeLine(out, "  ops deploy --entity <id> [--artifact <uri>] [-m <status>] [--stage-only|--commit]");
+  writeLine(out, "  verify");
+  writeLine(out, "  journal [--since <2h|2025-...>] [--limit N] [--types a,b] [--entity <id>] [--active]");
+  writeLine(out, "  hooks install|uninstall");
+  writeLine(out, "  webhook status");
+  writeLine(out, "  webhook test --url <url> [--type <type>]");
+  return 0;
+}
+
+

package/src/commands/hooks.ts

@@ -0,0 +1,40 @@
+import type { CommandArgs } from "./types.js";
+import fs from "node:fs/promises";
+import { gitPath } from "../git.js";
+
+export async function handleHooks(args: CommandArgs): Promise<number | undefined> {
+  if (args.positionals[0] !== "hooks") return;
+  const sub = args.positionals[1];
+  if (sub !== "install" && sub !== "uninstall") {
+    args.io.writeLine(args.io.err, "usage: git a5c hooks install|uninstall");
+    return 2;
+  }
+  const hooksDir = await gitPath(args.repoRoot, "hooks");
+  const hookFiles = ["post-commit", "post-merge"];
+  if (sub === "uninstall") {
+    for (const f of hookFiles) {
+      try {
+        const p = `${hooksDir}/${f}`;
+        const cur = await fs.readFile(p, "utf8");
+        if (cur.includes("A5C-HOOK-MANAGED: yes")) {
+          await fs.unlink(p);
+        }
+      } catch {}
+    }
+    args.io.writeLine(args.io.out, "ok");
+    return 0;
+  }
+  const script = `#!/bin/sh\n# a5cforge hook (generated)\n# A5C-HOOK-MANAGED: yes\n# Keep it quiet; write last journal to .git\nif command -v git >/dev/null 2>&1; then\n  git a5c journal --since 2h --limit 20 --json > "$(git rev-parse --git-path a5c-last-journal.json)" 2>/dev/null || true\nfi\nexit 0\n`;
+  await fs.mkdir(hooksDir, { recursive: true });
+  for (const f of hookFiles) {
+    const p = `${hooksDir}/${f}`;
+    await fs.writeFile(p, script, "utf8");
+    try {
+      await fs.chmod(p, 0o755);
+    } catch {}
+  }
+  args.io.writeLine(args.io.out, "ok");
+  return 0;
+}
+
+

package/src/commands/issue.ts

@@ -0,0 +1,146 @@
+import type { CommandArgs } from "./types.js";
+import { git, gitConfigGet } from "../git.js";
+import {
+  HlcClock,
+  UlidGenerator,
+  loadHlcState,
+  saveHlcState,
+  stageFiles,
+  listIssues,
+  renderIssue,
+  writeIssueCreated,
+  writeCommentCreated,
+  writeCommentEdited,
+  writeCommentRedacted
+} from "@a5cforge/sdk";
+
+export async function handleIssue(args: CommandArgs): Promise<number | undefined> {
+  if (args.positionals[0] !== "issue") return;
+  const sub = args.positionals[1];
+
+  if (sub === "list") {
+    const ids = listIssues(args.snap);
+    if (args.flags.json) args.io.writeLine(args.io.out, JSON.stringify(ids, null, 2));
+    else ids.forEach((id) => args.io.writeLine(args.io.out, id));
+    return 0;
+  }
+
+  if (sub === "show") {
+    const id = args.positionals[2];
+    if (!id) throw new Error("missing issue id");
+    const issue = renderIssue(args.snap, id);
+    if (!issue) {
+      args.io.writeLine(args.io.err, `not found: ${id}`);
+      return 2;
+    }
+    if (args.flags.json) args.io.writeLine(args.io.out, JSON.stringify(issue, null, 2));
+    else {
+      args.io.writeLine(args.io.out, `${issue.issueId}: ${issue.title}`);
+      if (issue.body) args.io.writeLine(args.io.out, issue.body);
+      args.io.writeLine(args.io.out, `comments: ${issue.comments.length}`);
+    }
+    return 0;
+  }
+
+  if (sub === "new") {
+    const title = args.flags.title;
+    if (!title) {
+      args.io.writeLine(args.io.err, "missing --title");
+      return 2;
+    }
+    const actor = process.env.A5C_ACTOR ?? (await gitConfigGet(args.repoRoot, "user.name")) ?? "unknown";
+    const issueId = args.flags.id ?? `issue-${new UlidGenerator().generate()}`;
+    const time = new Date(args.nowMs()).toISOString();
+    const persisted = (await loadHlcState(actor)) ?? { wallMs: 0, counter: 0 };
+    const clock = new HlcClock(persisted);
+    let nonce = 0;
+    const ctx = { repoRoot: args.repoRoot, actor, clock, nextNonce: () => String(++nonce).padStart(4, "0") };
+    const res = await writeIssueCreated(ctx, { issueId, title, body: args.flags.body, time });
+    await saveHlcState(actor, clock.now());
+    if (args.flags.stageOnly || args.flags.commit) await stageFiles(args.repoRoot, [res.path]);
+    if (args.flags.commit) {
+      const msg = args.flags.message ?? `a5c: issue new ${issueId}`;
+      await git(["-c", "user.name=a5c", "-c", "user.email=a5c@example.invalid", "commit", "-m", msg], args.repoRoot);
+    }
+    args.io.writeLine(args.io.out, issueId);
+    return 0;
+  }
+
+  if (sub === "comment") {
+    const id = args.positionals[2];
+    const body = args.flags.message ?? args.flags.body;
+    if (!id || !body) {
+      args.io.writeLine(args.io.err, "usage: git a5c issue comment <id> -m <text>");
+      return 2;
+    }
+    const actor = process.env.A5C_ACTOR ?? (await gitConfigGet(args.repoRoot, "user.name")) ?? "unknown";
+    const commentId = args.flags.commentId ?? `c-${new UlidGenerator().generate()}`;
+    const time = new Date(args.nowMs()).toISOString();
+    const persisted = (await loadHlcState(actor)) ?? { wallMs: 0, counter: 0 };
+    const clock = new HlcClock(persisted);
+    let nonce = 0;
+    const ctx = { repoRoot: args.repoRoot, actor, clock, nextNonce: () => String(++nonce).padStart(4, "0") };
+    const res = await writeCommentCreated(ctx, { entity: { type: "issue", id }, commentId, body: String(body), time });
+    await saveHlcState(actor, clock.now());
+    if (args.flags.stageOnly || args.flags.commit) await stageFiles(args.repoRoot, [res.path]);
+    if (args.flags.commit) {
+      const msg = args.flags.message ?? `a5c: issue comment ${id}`;
+      await git(["-c", "user.name=a5c", "-c", "user.email=a5c@example.invalid", "commit", "-m", msg], args.repoRoot);
+    }
+    args.io.writeLine(args.io.out, commentId);
+    return 0;
+  }
+
+  if (sub === "edit-comment") {
+    const commentId = args.positionals[2] ?? args.flags.commentId;
+    const body = args.flags.message ?? args.flags.body;
+    const id = args.flags.id; // entity id required for now
+    if (!commentId || !body || !id) {
+      args.io.writeLine(args.io.err, "usage: git a5c issue edit-comment <commentId> --id <issueId> -m <text>");
+      return 2;
+    }
+    const actor = process.env.A5C_ACTOR ?? (await gitConfigGet(args.repoRoot, "user.name")) ?? "unknown";
+    const time = new Date(args.nowMs()).toISOString();
+    const persisted = (await loadHlcState(actor)) ?? { wallMs: 0, counter: 0 };
+    const clock = new HlcClock(persisted);
+    let nonce = 0;
+    const ctx = { repoRoot: args.repoRoot, actor, clock, nextNonce: () => String(++nonce).padStart(4, "0") };
+    const res = await writeCommentEdited(ctx, { entity: { type: "issue", id }, commentId, body: String(body), time });
+    await saveHlcState(actor, clock.now());
+    if (args.flags.stageOnly || args.flags.commit) await stageFiles(args.repoRoot, [res.path]);
+    if (args.flags.commit) {
+      const msg = args.flags.message ?? `a5c: issue edit-comment ${id} ${commentId}`;
+      await git(["-c", "user.name=a5c", "-c", "user.email=a5c@example.invalid", "commit", "-m", msg], args.repoRoot);
+    }
+    args.io.writeLine(args.io.out, res.path);
+    return 0;
+  }
+
+  if (sub === "redact-comment") {
+    const commentId = args.positionals[2] ?? args.flags.commentId;
+    const id = args.flags.id;
+    if (!commentId || !id) {
+      args.io.writeLine(args.io.err, "usage: git a5c issue redact-comment <commentId> --id <issueId> [--reason ...]");
+      return 2;
+    }
+    const actor = process.env.A5C_ACTOR ?? (await gitConfigGet(args.repoRoot, "user.name")) ?? "unknown";
+    const time = new Date(args.nowMs()).toISOString();
+    const persisted = (await loadHlcState(actor)) ?? { wallMs: 0, counter: 0 };
+    const clock = new HlcClock(persisted);
+    let nonce = 0;
+    const ctx = { repoRoot: args.repoRoot, actor, clock, nextNonce: () => String(++nonce).padStart(4, "0") };
+    const res = await writeCommentRedacted(ctx, { entity: { type: "issue", id }, commentId, reason: args.flags.reason, time });
+    await saveHlcState(actor, clock.now());
+    if (args.flags.stageOnly || args.flags.commit) await stageFiles(args.repoRoot, [res.path]);
+    if (args.flags.commit) {
+      const msg = args.flags.message ?? `a5c: issue redact-comment ${id} ${commentId}`;
+      await git(["-c", "user.name=a5c", "-c", "user.email=a5c@example.invalid", "commit", "-m", msg], args.repoRoot);
+    }
+    args.io.writeLine(args.io.out, res.path);
+    return 0;
+  }
+
+  return;
+}
+
+