@brawnen/agent-harness-cli 0.1.0

package/src/commands/task.js

@@ -0,0 +1,316 @@
+import { createTaskFromInput, suspendActiveTask } from "../lib/task-core.js";
+import { normalizeOutputPolicy } from "../lib/output-policy.js";
+import { loadProjectConfig } from "../lib/project-config.js";
+import { confirmTaskContract, resolveTaskId, updateTaskState } from "../lib/state-store.js";
+import { evaluateTaskWorkflowDecision, normalizeWorkflowPolicy } from "../lib/workflow-policy.js";
+
+export function runTask(argv) {
+  const [subcommand, ...rest] = argv;
+
+  if (!subcommand) {
+    console.error("缺少 task 子命令。可用: intake, suspend-active");
+    return 1;
+  }
+
+  if (subcommand === "intake") {
+    return runTaskIntake(rest);
+  }
+
+  if (subcommand === "confirm" || subcommand === "confirm-contract") {
+    return runTaskConfirm(rest);
+  }
+
+  if (subcommand === "suspend-active" || subcommand === "suspend-active-task") {
+    return runTaskSuspendActive(rest);
+  }
+
+  console.error(`未知 task 子命令: ${subcommand}。可用: intake, confirm, suspend-active`);
+  return 1;
+}
+
+function runTaskIntake(argv) {
+  const parsed = parseTaskIntakeArgs(argv);
+  if (!parsed.ok) {
+    console.error(parsed.error);
+    return 1;
+  }
+
+  try {
+    const result = createTaskFromInput(process.cwd(), parsed.options.input, parsed.options);
+    printJson(result);
+    return 0;
+  } catch (error) {
+    console.error(error.message);
+    return 1;
+  }
+}
+
+function runTaskSuspendActive(argv) {
+  const parsed = parseTaskSuspendArgs(argv);
+  if (!parsed.ok) {
+    console.error(parsed.error);
+    return 1;
+  }
+
+  try {
+    const result = suspendActiveTask(process.cwd(), {
+      reason: parsed.options.reason,
+      clearActive: true
+    });
+    printJson(result);
+    return 0;
+  } catch (error) {
+    console.error(error.message);
+    return 1;
+  }
+}
+
+function runTaskConfirm(argv) {
+  const parsed = parseTaskConfirmArgs(argv);
+  if (!parsed.ok) {
+    console.error(parsed.error);
+    return 1;
+  }
+
+  try {
+    const cwd = process.cwd();
+    const taskId = resolveTaskId(cwd, parsed.options.taskId);
+    const confirmed = confirmTaskContract(cwd, taskId, parsed.options);
+    const projectConfig = loadProjectConfig(cwd);
+    const workflowDecision = evaluateTaskWorkflowDecision(confirmed, {
+      workflowPolicy: normalizeWorkflowPolicy(projectConfig?.workflow_policy),
+      outputPolicy: normalizeOutputPolicy(projectConfig?.output_policy),
+      previousDecision: confirmed.workflow_decision
+    });
+    const result = updateTaskState(cwd, taskId, {
+      workflow_decision: workflowDecision
+    });
+    printJson(result);
+    return 0;
+  } catch (error) {
+    console.error(error.message);
+    return 1;
+  }
+}
+
+function parseTaskIntakeArgs(argv) {
+  const options = {
+    acceptance: [],
+    assumptions: [],
+    constraints: [],
+    contextRefs: [],
+    goal: null,
+    input: null,
+    intent: null,
+    mode: null,
+    scope: [],
+    suspendActive: false,
+    suspendReason: null,
+    taskId: null,
+    title: null
+  };
+
+  const positional = [];
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+
+    if (!arg.startsWith("--")) {
+      positional.push(arg);
+      continue;
+    }
+
+    if (arg === "--input") {
+      options.input = argv[index + 1] ?? null;
+      index += 1;
+      continue;
+    }
+    if (arg === "--intent") {
+      options.intent = argv[index + 1] ?? null;
+      index += 1;
+      continue;
+    }
+    if (arg === "--goal") {
+      options.goal = argv[index + 1] ?? null;
+      index += 1;
+      continue;
+    }
+    if (arg === "--scope") {
+      options.scope.push(argv[index + 1] ?? "");
+      index += 1;
+      continue;
+    }
+    if (arg === "--acceptance") {
+      options.acceptance.push(argv[index + 1] ?? "");
+      index += 1;
+      continue;
+    }
+    if (arg === "--constraint") {
+      options.constraints.push(argv[index + 1] ?? "");
+      index += 1;
+      continue;
+    }
+    if (arg === "--assumption") {
+      options.assumptions.push(argv[index + 1] ?? "");
+      index += 1;
+      continue;
+    }
+    if (arg === "--context-ref") {
+      options.contextRefs.push(argv[index + 1] ?? "");
+      index += 1;
+      continue;
+    }
+    if (arg === "--mode") {
+      options.mode = argv[index + 1] ?? null;
+      index += 1;
+      continue;
+    }
+    if (arg === "--task-id") {
+      options.taskId = argv[index + 1] ?? null;
+      index += 1;
+      continue;
+    }
+    if (arg === "--title") {
+      options.title = argv[index + 1] ?? null;
+      index += 1;
+      continue;
+    }
+    if (arg === "--suspend-active") {
+      options.suspendActive = true;
+      continue;
+    }
+    if (arg === "--suspend-reason") {
+      options.suspendReason = argv[index + 1] ?? null;
+      index += 1;
+      continue;
+    }
+
+    return { ok: false, error: `未知参数: ${arg}` };
+  }
+
+  if (!options.input && positional.length > 0) {
+    options.input = positional.join(" ");
+  }
+
+  if (!options.input) {
+    return { ok: false, error: "需要任务描述。用法: task intake \"<任务描述>\" 或 --input" };
+  }
+
+  return { ok: true, options };
+}
+
+function parseTaskSuspendArgs(argv) {
+  const options = {
+    reason: "用户显式要求挂起当前活跃任务。"
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+
+    if (arg === "--reason") {
+      options.reason = argv[index + 1] ?? null;
+      index += 1;
+      continue;
+    }
+
+    return { ok: false, error: `未知参数: ${arg}` };
+  }
+
+  return { ok: true, options };
+}
+
+function parseTaskConfirmArgs(argv) {
+  const options = {
+    acceptance: [],
+    constraints: [],
+    contextRefs: [],
+    evidenceRequired: [],
+    goal: null,
+    id: null,
+    intent: null,
+    mode: null,
+    riskLevel: null,
+    scope: [],
+    taskId: null,
+    title: null,
+    verification: []
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+
+    if (arg === "--task-id") {
+      options.taskId = argv[index + 1] ?? null;
+      index += 1;
+      continue;
+    }
+    if (arg === "--intent") {
+      options.intent = argv[index + 1] ?? null;
+      index += 1;
+      continue;
+    }
+    if (arg === "--goal") {
+      options.goal = argv[index + 1] ?? null;
+      index += 1;
+      continue;
+    }
+    if (arg === "--scope") {
+      options.scope.push(argv[index + 1] ?? "");
+      index += 1;
+      continue;
+    }
+    if (arg === "--acceptance") {
+      options.acceptance.push(argv[index + 1] ?? "");
+      index += 1;
+      continue;
+    }
+    if (arg === "--constraint") {
+      options.constraints.push(argv[index + 1] ?? "");
+      index += 1;
+      continue;
+    }
+    if (arg === "--context-ref") {
+      options.contextRefs.push(argv[index + 1] ?? "");
+      index += 1;
+      continue;
+    }
+    if (arg === "--verification") {
+      options.verification.push(argv[index + 1] ?? "");
+      index += 1;
+      continue;
+    }
+    if (arg === "--evidence-required") {
+      options.evidenceRequired.push(argv[index + 1] ?? "");
+      index += 1;
+      continue;
+    }
+    if (arg === "--mode") {
+      options.mode = argv[index + 1] ?? null;
+      index += 1;
+      continue;
+    }
+    if (arg === "--title") {
+      options.title = argv[index + 1] ?? null;
+      index += 1;
+      continue;
+    }
+    if (arg === "--id") {
+      options.id = argv[index + 1] ?? null;
+      index += 1;
+      continue;
+    }
+    if (arg === "--risk-level") {
+      options.riskLevel = argv[index + 1] ?? null;
+      index += 1;
+      continue;
+    }
+
+    return { ok: false, error: `未知参数: ${arg}` };
+  }
+
+  return { ok: true, options };
+}
+
+function printJson(value) {
+  console.log(`${JSON.stringify(value, null, 2)}\n`);
+}

package/src/commands/verify.js

@@ -0,0 +1,173 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { loadProjectConfig } from "../lib/project-config.js";
+import { resolveTaskId, requireTaskState } from "../lib/state-store.js";
+
+const VERIFICATION_MATRIX = {
+  bug: {
+    description: "至少一条命令或测试证明问题不再复现",
+    deterministic: true,
+    requiredTypes: ["command_result", "test_result"]
+  },
+  feature: {
+    description: "至少一条命令或验证动作证明新能力可运行",
+    deterministic: true,
+    requiredTypes: ["command_result"]
+  },
+  refactor: {
+    description: "至少一条测试证明行为未破坏",
+    deterministic: true,
+    requiredTypes: ["test_result"]
+  },
+  explore: {
+    description: "至少有结论、依据、风险与下一步建议",
+    deterministic: false,
+    requiredTypes: ["reasoning_note"]
+  },
+  prototype: {
+    description: "可无强制验证，但必须明确未验证范围",
+    deterministic: false,
+    requiredTypes: ["reasoning_note"]
+  }
+};
+
+export function runVerify(argv) {
+  const parsed = parseVerifyArgs(argv);
+  if (!parsed.ok) {
+    console.error(parsed.error);
+    return 1;
+  }
+
+  let taskState;
+  const cwd = process.cwd();
+  try {
+    const taskId = parsed.options.taskFile
+      ? null
+      : resolveTaskId(cwd, parsed.options.taskId);
+    taskState = parsed.options.taskFile
+      ? readTaskFile(cwd, parsed.options.taskFile)
+      : requireTaskState(cwd, taskId);
+  } catch (error) {
+    console.error(error.message);
+    return 1;
+  }
+
+  const projectConfig = loadProjectConfig(cwd);
+  const result = verifyTaskState(taskState, {
+    reportPolicy: normalizeReportPolicy(projectConfig?.output_policy?.report)
+  });
+  console.log(`${JSON.stringify(result, null, 2)}\n`);
+  return result.allowed ? 0 : 1;
+}
+
+function parseVerifyArgs(argv) {
+  const options = {
+    taskFile: null,
+    taskId: null
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+
+    if (arg === "--task-id") {
+      const value = argv[index + 1];
+      if (!value) {
+        return { ok: false, error: "缺少 --task-id 参数值" };
+      }
+      options.taskId = value;
+      index += 1;
+      continue;
+    }
+
+    if (arg === "--task-file") {
+      const value = argv[index + 1];
+      if (!value) {
+        return { ok: false, error: "缺少 --task-file 参数值" };
+      }
+      options.taskFile = value;
+      index += 1;
+      continue;
+    }
+
+    return { ok: false, error: `未知参数: ${arg}` };
+  }
+
+  if (options.taskId && options.taskFile) {
+    return { ok: false, error: "--task-id 与 --task-file 不能同时使用" };
+  }
+
+  return { ok: true, options };
+}
+
+export function verifyTaskState(taskState, options = {}) {
+  const intent = taskState?.confirmed_contract?.intent ?? taskState?.task_draft?.intent ?? "unknown";
+  const acceptance = taskState?.confirmed_contract?.acceptance ?? taskState?.task_draft?.acceptance ?? [];
+  const evidence = Array.isArray(taskState?.evidence) ? taskState.evidence : [];
+  const openQuestions = Array.isArray(taskState?.open_questions) ? taskState.open_questions : [];
+  const missingEvidence = [];
+  const reportPolicy = normalizeReportPolicy(options.reportPolicy);
+
+  if (openQuestions.length > 0) {
+    missingEvidence.push(`存在未关闭的阻断问题: ${openQuestions[0]}`);
+  }
+
+  const matrix = VERIFICATION_MATRIX[intent];
+  if (!matrix) {
+    missingEvidence.push(`未知的 intent 类型: ${intent}，无法匹配验证矩阵`);
+  } else {
+    const hasRequired = matrix.requiredTypes.some((type) => evidence.some((item) => item.type === type));
+    if (!hasRequired) {
+      missingEvidence.push(`${matrix.description}（需要: ${matrix.requiredTypes.join(" 或 ")}）`);
+    }
+
+    if (matrix.deterministic) {
+      const deterministicEvidence = evidence.filter((item) => matrix.requiredTypes.includes(item.type));
+      const allFailed =
+        deterministicEvidence.length > 0 &&
+        deterministicEvidence.every((item) => item.passed === false || (typeof item.exit_code === "number" && item.exit_code !== 0));
+
+      if (allFailed) {
+        missingEvidence.push("已有验证结果但全部失败");
+      }
+    }
+  }
+
+  if (!Array.isArray(acceptance) || acceptance.length === 0) {
+    missingEvidence.push("未定义 acceptance 标准");
+  }
+
+  return {
+    allowed: missingEvidence.length === 0,
+    intent,
+    missing_evidence: missingEvidence,
+    report_policy: reportPolicy,
+    signal: missingEvidence.length === 0 ? "allow_completion" : "block_completion",
+    task_id: taskState.task_id ?? null
+  };
+}
+
+function readTaskFile(cwd, taskFile) {
+  const filePath = path.resolve(cwd, taskFile);
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`文件不存在: ${filePath}`);
+  }
+
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch {
+    throw new Error(`JSON 解析失败: ${filePath}`);
+  }
+}
+
+function normalizeReportPolicy(value) {
+  const policy = value && typeof value === "object" && !Array.isArray(value) ? value : {};
+  return {
+    required: policy.required !== false,
+    format: typeof policy.format === "string" ? policy.format : "json",
+    directory: typeof policy.directory === "string" ? policy.directory : ".harness/reports",
+    required_sections: Array.isArray(policy.required_sections)
+      ? policy.required_sections.map((item) => String(item))
+      : []
+  };
+}

package/src/index.js

@@ -0,0 +1,101 @@
+import { runAudit } from "./commands/audit.js";
+import { runDelivery } from "./commands/delivery.js";
+import { runDocs } from "./commands/docs.js";
+import { runGate } from "./commands/gate.js";
+import { runInit } from "./commands/init.js";
+import { runReport } from "./commands/report.js";
+import { runState } from "./commands/state.js";
+import { runStatus } from "./commands/status.js";
+import { runTask } from "./commands/task.js";
+import { runVerify } from "./commands/verify.js";
+
+const HELP_TEXT = `agent-harness CLI
+
+Usage:
+  agent-harness --help
+  agent-harness --version
+  agent-harness init
+  agent-harness init --dry-run
+  agent-harness init --protocol-only
+  agent-harness audit <append|read>
+  agent-harness delivery <ready|request|commit>
+  agent-harness docs scaffold --type <design-note|adr>
+  agent-harness gate before-tool --tool <tool>
+  agent-harness status
+  agent-harness task intake "<任务描述>"
+  agent-harness task confirm [--task-id <task-id>]
+  agent-harness task suspend-active
+  agent-harness state <init|get|update|active>
+  agent-harness verify
+  agent-harness verify --task-id <task-id>
+  agent-harness report --conclusion <text>
+
+Options:
+  --host <auto|claude-code|codex|gemini-cli>
+  --rules <base|full>
+  --mode <delivery|explore|poc>
+  --dry-run
+  --protocol-only
+  --force
+
+Status:
+  task/init/status/state/verify/report/gate/audit/delivery/docs MVP are implemented.
+`;
+
+export function run(argv) {
+  const [command] = argv;
+
+  if (!command || command === "--help" || command === "-h") {
+    console.log(HELP_TEXT);
+    return 0;
+  }
+
+  if (command === "--version" || command === "-v") {
+    console.log("0.1.0");
+    return 0;
+  }
+
+  if (command === "init") {
+    return runInit(argv.slice(1));
+  }
+
+  if (command === "audit") {
+    return runAudit(argv.slice(1));
+  }
+
+  if (command === "delivery") {
+    return runDelivery(argv.slice(1));
+  }
+
+  if (command === "docs") {
+    return runDocs(argv.slice(1));
+  }
+
+  if (command === "gate") {
+    return runGate(argv.slice(1));
+  }
+
+  if (command === "status") {
+    return runStatus(argv.slice(1));
+  }
+
+  if (command === "task") {
+    return runTask(argv.slice(1));
+  }
+
+  if (command === "state") {
+    return runState(argv.slice(1));
+  }
+
+  if (command === "verify") {
+    return runVerify(argv.slice(1));
+  }
+
+  if (command === "report") {
+    return runReport(argv.slice(1));
+  }
+
+  console.error(`未知命令: ${command}`);
+  console.error("运行 `agent-harness --help` 查看可用命令。");
+  return 1;
+}

package/src/lib/audit-store.js

@@ -0,0 +1,80 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { runtimePath } from "./runtime-paths.js";
+
+const VALID_EVENT_TYPES = [
+  "force_override",
+  "gate_violation",
+  "remediation",
+  "state_recovery",
+  "manual_confirmation"
+];
+const VALID_PHASES = ["intake", "clarify", "plan", "execute", "verify", "report", "close"];
+const VALID_RISK_LEVELS = ["low", "medium", "high", "unknown"];
+
+export function appendAuditEntry(cwd, entry) {
+  validateEntry(entry);
+
+  const nextEntry = {
+    event_type: entry.event_type,
+    task_id: entry.task_id,
+    phase: entry.phase,
+    signal: entry.signal,
+    description: entry.description,
+    user_input: entry.user_input ?? null,
+    risk_at_time: entry.risk_at_time ?? "unknown",
+    timestamp: entry.timestamp ?? new Date().toISOString()
+  };
+
+  const auditDir = auditDirPath(cwd);
+  fs.mkdirSync(auditDir, { recursive: true });
+  const filePath = path.join(auditDir, `${entry.task_id}.jsonl`);
+  fs.appendFileSync(filePath, `${JSON.stringify(nextEntry)}\n`, "utf8");
+  return nextEntry;
+}
+
+export function readAuditEntries(cwd, taskId) {
+  const filePath = path.join(auditDirPath(cwd), `${taskId}.jsonl`);
+  if (!fs.existsSync(filePath)) {
+    return [];
+  }
+
+  return fs
+    .readFileSync(filePath, "utf8")
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => JSON.parse(line));
+}
+
+function auditDirPath(cwd) {
+  return runtimePath(cwd, "audit");
+}
+
+function validateEntry(entry) {
+  if (!VALID_EVENT_TYPES.includes(entry.event_type)) {
+    throw new Error(`无效的 event_type: ${entry.event_type}`);
+  }
+
+  if (!VALID_PHASES.includes(entry.phase)) {
+    throw new Error(`无效的 phase: ${entry.phase}`);
+  }
+
+  const riskLevel = entry.risk_at_time ?? "unknown";
+  if (!VALID_RISK_LEVELS.includes(riskLevel)) {
+    throw new Error(`无效的 risk_at_time: ${riskLevel}`);
+  }
+
+  if (!entry.task_id) {
+    throw new Error("缺少 task_id");
+  }
+
+  if (!entry.signal) {
+    throw new Error("缺少 signal");
+  }
+
+  if (!entry.description) {
+    throw new Error("缺少 description");
+  }
+}