@brawnen/agent-harness-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 brawnen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,224 @@
+# @brawnen/agent-harness-cli
+
+[中文](README.zh-CN.md)
+
+`@brawnen/agent-harness-cli` is the Node.js CLI for `agent-harness`.
+
+It is the runtime layer that turns protocol rules into a working task loop with:
+
+- initialization
+- task state
+- verification
+- reports
+- gating
+- audit
+- delivery
+- documentation scaffolding
+
+## Current Coverage
+
+The CLI currently includes these commands:
+
+- `init`
+- `status`
+- `task`
+- `state`
+- `verify`
+- `report`
+- `gate`
+- `audit`
+- `delivery`
+- `docs`
+
+The current implementation also covers:
+
+- `--dry-run`
+- `--protocol-only`
+- host rule injection
+- base project config generation
+- minimal `.codex/hooks.json` integration
+
+## Current Boundaries
+
+The CLI is already usable, but it is still an evolving implementation.
+
+It currently does not try to provide:
+
+- a fully general host integration layer for every host
+- a full shell parser for `Bash`
+- automatic `git push`
+- a deep upgrader / migration system
+
+## What The CLI Does Today
+
+### `init`
+
+Current responsibilities:
+
+- detect project type
+- detect host type
+- generate `harness.yaml`
+- copy task templates into `.harness/tasks/`
+- inject rule blocks into `CLAUDE.md`, `AGENTS.md`, or `GEMINI.md`
+- create minimal runtime directories when not using `--protocol-only`
+
+### `task`
+
+Current responsibilities:
+
+- `task intake`
+- `task confirm`
+- `task suspend-active`
+- create a minimal task draft from natural language
+- close that draft into a confirmed contract
+- provide reusable intake/suspend logic for Codex hooks
+
+### `state`
+
+Current responsibilities:
+
+- `state init`
+- `state get`
+- `state update`
+- `state active`
+- maintain `.harness/state/index.json`
+- maintain `.harness/state/tasks/<task_id>.json`
+
+### `verify`
+
+Current responsibilities:
+
+- read the active task or an explicit `--task-id`
+- evaluate minimal completion requirements
+- return structured JSON
+- distinguish allow vs block via exit code
+
+### `report`
+
+Current responsibilities:
+
+- reuse `verify` before report generation
+- write `.harness/reports/<task_id>.json`
+- move the task to `close / done`
+- validate required output artifacts such as `CHANGELOG.md`, `design note`, and `ADR`
+- compute `delivery_readiness`
+
+### `gate`
+
+Current responsibilities:
+
+- `gate before-tool`
+- deterministic checks for write state legality
+- `protected_paths`
+- path-like scope boundaries
+- high-risk confirmation requirements
+
+### `audit`
+
+Current responsibilities:
+
+- `audit append`
+- `audit read`
+- write `.harness/audit/<task_id>.jsonl`
+- record minimal `gate_violation`
+- expose `force_override` and `manual_confirmation`
+
+### `delivery`
+
+Current responsibilities:
+
+- `delivery ready`
+- `delivery request --action commit|push`
+- `delivery commit`
+- explicit local commit flow
+
+Current delivery boundary:
+
+- `commit` is supported as an explicit action
+- `push` remains manual
+
+### `docs`
+
+Current responsibilities:
+
+- `docs scaffold --type design-note|adr`
+- generate minimal Markdown skeletons from task context
+
+## Codex Support
+
+The current repository has the most complete host integration for `Codex`.
+
+Current Codex coverage includes:
+
+- `SessionStart`
+- `UserPromptSubmit`
+- `PreToolUse`
+- `PostToolUse`
+
+Highlights:
+
+- automatic intake / continue / clarify
+- pre-tool gating
+- automatic evidence capture
+- active task restore
+
+### Current `PreToolUse` Coverage For `Bash`
+
+`Bash` currently supports high-confidence path inference for common write commands such as:
+
+- `echo ... > file`
+- `cat <<EOF > file`
+- `tee file`
+- `printf ... | tee file`
+- `mkdir -p dir`
+- `touch file`
+- `sed -i file`
+- `perl -pi file`
+- `chmod/chown/chgrp target`
+- `rm file`
+- `truncate -s ... file`
+- `dd ... of=file`
+- `mv src dst`
+- `cp src dst`
+- `install -d dir`
+- `install -D/-m ... dst`
+- `install -Dm644 src dst`
+- `install src dst`
+- `ln -s src dst`
+- `rsync ... dst`
+
+If the target path cannot be inferred with high confidence, the CLI degrades conservatively and only applies state-level gating.
+
+## Validation Helpers
+
+Useful local checks:
+
+```bash
+npm --prefix packages/cli run verify:task-core
+npm --prefix packages/cli run verify:codex-e2e
+```
+
+From the repository root:
+
+```bash
+npm run codex:hooks:check
+npm run codex:e2e
+```
+
+## Local Invocation Note
+
+If your current working directory is not the repository root, prefer calling the CLI with an absolute path, for example:
+
+```bash
+node /abs/path/to/agent-harness/packages/cli/bin/agent-harness.js status
+```
+
+Do not assume `node packages/cli/bin/agent-harness.js ...` will work from an arbitrary temporary directory.
+
+## Design Constraint
+
+- the CLI depends on `@brawnen/agent-harness-protocol`
+- installing `@brawnen/agent-harness-cli` from npm should automatically pull `@brawnen/agent-harness-protocol`
+- the protocol must not depend on the CLI
+- the default npm entrypoint is `npx @brawnen/agent-harness-cli init`
+- this repository currently treats the Node.js CLI as the only mainline implementation

package/README.zh-CN.md

@@ -0,0 +1,232 @@
+# @brawnen/agent-harness-cli
+
+[English](README.md)
+
+这是 `agent-harness` 的 Node.js CLI。
+
+当前已完成：
+
+- 可执行入口
+- `task` MVP
+- `init` MVP
+- `status` MVP
+- `verify` MVP
+- `state` MVP
+- `report` MVP
+- `gate` MVP
+- `audit` MVP
+- `docs` MVP
+- `--dry-run`
+- `--protocol-only`
+- 宿主规则注入
+- 基础项目配置生成
+- `.codex/hooks.json` 最小方案
+
+还未完成：
+
+- 更深的宿主集成
+
+`init` MVP 当前负责：
+
+- 检测项目类型
+- 检测宿主类型
+- 生成 `harness.yaml`
+- 复制协议任务模板到 `.harness/tasks/`
+- 注入 `CLAUDE.md` / `AGENTS.md` / `GEMINI.md` 规则块
+- 在非 `--protocol-only` 模式下生成运行时目录和 Claude Code hooks
+
+`task` MVP 当前负责：
+
+- `task intake "<任务描述>"`
+- `task confirm`
+- `task suspend-active`
+- 从自然语言生成最小 task draft
+- 将 task draft 闭合为 confirmed contract
+- 在可选 `--suspend-active` 时挂起旧任务
+- 为 Codex hook 提供可复用的 intake / suspend 内核
+
+当前不负责：
+
+- 完整状态管理迁移
+- 完整 gate / audit / report 迁移
+- 复杂升级与深度 merge
+
+`task-core` 当前已经补了最小分类回归样本，可在本地运行：
+
+```bash
+npm --prefix packages/cli run verify:task-core
+```
+
+这组样本当前覆盖：
+
+- `matched_continue_keyword`
+- `matched_new_task_keyword`
+- `matched_active_goal_fragment`
+- `matched_active_scope`
+- `ambiguous_high_risk_prompt`
+- `fallback_new_task`
+- `inactive_active_task_state`
+- `no_active_task`
+
+`status` MVP 当前负责：
+
+- 检查 `harness.yaml`
+- 检查宿主规则块
+- 检查任务模板目录
+- 检查 Claude Code hooks
+- 检查运行时目录与 `.gitignore`
+- 用退出码区分完整、警告和不完整
+
+`verify` MVP 当前负责：
+
+- 读取 `.harness/state/index.json` 中的 active task，或显式 `--task-id`
+- 读取 `.harness/state/tasks/<task_id>.json`
+- 按最小验证矩阵检查 `intent / evidence / open_questions / acceptance`
+- 输出结构化 JSON 结果
+- 用退出码区分允许完成和阻止完成
+
+`state` MVP 当前负责：
+
+- `state init`
+- `state get`
+- `state update`
+- `state active`
+- 维护 `.harness/state/index.json`
+- 维护 `.harness/state/tasks/<task_id>.json`
+- 复用最小合法状态迁移表
+
+`report` MVP 当前负责：
+
+- 读取 active task 或显式 `--task-id`
+- 在生成报告前复用 `verify` 规则做完成门禁检查
+- 写入 `.harness/reports/<task_id>.json`
+- 将任务状态推进到 `close / done`
+- 根据 `output_policy` 校验 `CHANGELOG.md`、`design note`、`ADR` 等交付工件
+- 根据 `delivery_policy` 计算 `commit-ready / push-ready`，并把 `delivery_readiness` 写进报告
+
+`report` 额外支持：
+
+- `--changelog-file <path>`
+- `--design-note <path>`
+- `--adr <path>`
+
+`gate` MVP 当前负责：
+
+- `gate before-tool`
+- 基于 active task 或显式 `--task-id` 做确定性门禁判断
+- 检查写入工具的任务状态是否合法
+- 检查 `protected_paths`
+- 检查路径是否越过 path-like scope
+- 在高风险且未确认时返回 `require_confirmation`
+
+`audit` MVP 当前负责：
+
+- `audit append`
+- `audit read`
+- 写入 `.harness/audit/<task_id>.jsonl`
+- 让 `gate` 记录最小 `gate_violation`
+- 让 `report` 读取 `force_override/manual_confirmation` 作为 `overrides_used`
+
+`delivery_policy` 第一版当前负责：
+
+- 在 `status` 中展示 active task 的 `commit-ready / push-ready`
+- 在 `report` 中输出 `delivery_readiness`
+- 提供 `delivery ready`、`delivery request --action commit|push` 和 `delivery commit` 入口
+- `commit` 保留为 skill 化的显式动作
+- `push` 保留为人工动作，不作为 skill 默认能力
+- 当前只做 readiness 计算，不会自动执行 `git commit` 或 `git push`
+- `commit_exists` 会基于任务报告中的 `actual_scope + output_artifacts` 检查相关文件是否仍有未提交改动
+- 若任务相关文件已经干净，则视为该任务已完成本地 `commit`
+
+`delivery commit` 当前行为：
+
+- 先复用 `delivery request --action commit`
+- 读取任务报告中的 `actual_scope` 和 `output_artifacts`
+- 目录型 scope 只会展开为当前有变更的文件
+- 支持 `--dry-run` 先预览提交计划
+- 对明显过宽的目录 scope 默认阻断，需显式使用 `--force-wide-scope`
+- 自动执行本地 `git add` / `git commit`
+- 永远不会执行 `git push`
+
+`docs scaffold` 当前行为：
+
+- 提供 `docs scaffold --type design-note|adr`
+- 默认读取 active task，也支持 `--task-id`
+- 根据任务上下文生成最小 Markdown 骨架
+- 默认写入 `output_policy.design_note.directory` 或 `output_policy.adr.directory`
+- 支持 `--path` 自定义目标路径
+- 已存在文件默认阻止覆盖，需显式使用 `--force`
+
+当 `report` 因缺少 `design_note` 或 `adr` 被阻断时：
+
+- 会直接输出对应的 `docs scaffold` 建议命令
+- 并给出重新执行 `report` 时应补的 `--design-note` / `--adr` 参数
+
+`status` 当前也会对 active task 主动给出 output artifact 提示：
+
+- 若当前任务要求 `changelog / design_note / adr`
+- 会直接提示建议补齐的工件
+- 对 `design_note / adr` 会给出可直接执行的 `docs scaffold` 命令
+
+Codex 自动 evidence：
+
+- 当前仓库在 `Codex` 下已为 `Bash` 接入 `PostToolUse`
+- 常见 Bash 命令结果会自动追加到 active task 的 `evidence`
+- 若命令明显属于测试，或任务当前处于 `verify` 阶段，则会优先记录为 `test_result`
+- 在高风险任务上，`UserPromptSubmit` 会把显式确认语句自动记录为 `manual_confirmation`
+- `别问了直接做`、`跳过验证` 这类显式 override 语句会自动记录为 `force_override`
+
+Codex `PreToolUse` 当前行为：
+
+- 会在 `Write / Edit / NotebookEdit / Bash` 前调用 `gate before-tool`
+- `needs_clarification / draft / blocked / failed / done / suspended` 状态下的写入会被前置阻断
+- 会结合 task state 与 `harness.yaml risk_rules.path_matches` 动态判断高风险写入
+- 高风险写入且未确认时，会在工具执行前阻断并要求先确认
+- `Bash` 当前已支持最小高置信路径提取，例如：
+  - `echo ... > file`
+  - `cat <<EOF > file`
+  - `tee file`
+  - `printf ... | tee file`
+  - `mkdir -p dir`
+  - `touch file`
+  - `sed -i file`
+  - `perl -pi file`
+  - `chmod/chown/chgrp target`
+  - `rm file`
+  - `truncate -s ... file`
+  - `dd ... of=file`
+  - `mv src dst`
+  - `cp src dst`
+  - `install -d dir`
+  - `install -D/-m ... dst`
+  - `install -Dm644 src dst`
+  - `install src dst`
+  - `ln -s src dst`
+  - `rsync ... dst`
+- 无法高置信提取目标路径时，会保守降级为仅做状态级门禁
+
+本地验证提示：
+
+- 如果当前工作目录不是仓库根目录，调用 CLI 时应使用绝对路径，例如：
+
+```bash
+node /abs/path/to/agent-harness/packages/cli/bin/agent-harness.js audit read --task-id <task-id>
+```
+
+- 不要在临时目录里直接运行相对路径 `node packages/cli/bin/agent-harness.js ...`，否则容易把路径错误误判成命令读取异常
+
+Codex E2E 回归：
+
+- 可执行 `npm --prefix packages/cli run verify:codex-e2e`
+- 或在仓库根目录执行 `npm run codex:e2e`
+- 当前最小回归覆盖：新任务自动 intake、follow-up 不误切、高风险确认链路、hook 降级提示
+- 当前回归采用“真实 `codex exec` smoke + hook 主链路回归”混合方式，优先验证我们自己的接入链路
+- 当前脚本会在**当前 trusted 仓库**里执行真实 Codex 回归，并清理自己创建的 task/audit/report 文件
+- 运行前要求当前仓库没有 active task
+
+设计约束：
+
+- CLI 依赖 `@brawnen/agent-harness-protocol`
+- 从 npm 安装 `@brawnen/agent-harness-cli` 时，应自动带上 `@brawnen/agent-harness-protocol`
+- 默认 npm 入口是 `npx @brawnen/agent-harness-cli init`
+- 当前仓库以 Node.js CLI 作为唯一主线实现

package/bin/agent-harness.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+
+import { run } from "../src/index.js";
+
+const exitCode = run(process.argv.slice(2));
+process.exit(exitCode);

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@brawnen/agent-harness-cli",
+  "version": "0.1.0",
+  "description": "CLI for task convergence, verification, reporting, and delivery in agent-harness projects.",
+  "license": "MIT",
+  "bin": {
+    "agent-harness": "./bin/agent-harness.js"
+  },
+  "type": "module",
+  "files": [
+    "bin",
+    "src",
+    "LICENSE",
+    "README.md",
+    "README.zh-CN.md"
+  ],
+  "keywords": [
+    "agent",
+    "ai",
+    "workflow",
+    "task",
+    "codex",
+    "cli"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/brawnen/agent-harness.git",
+    "directory": "packages/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/brawnen/agent-harness/issues"
+  },
+  "homepage": "https://github.com/brawnen/agent-harness/tree/main/packages/cli",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@brawnen/agent-harness-protocol": "^0.1.0"
+  },
+  "scripts": {
+    "start": "node ./bin/agent-harness.js --help"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/commands/audit.js

@@ -0,0 +1,110 @@
+import { appendAuditEntry, readAuditEntries } from "../lib/audit-store.js";
+
+export function runAudit(argv) {
+  const [subcommand, ...rest] = argv;
+
+  if (subcommand === "append") {
+    return runAuditAppend(rest);
+  }
+
+  if (subcommand === "read") {
+    return runAuditRead(rest);
+  }
+
+  console.error("audit 可用子命令: append, read");
+  return 1;
+}
+
+function runAuditAppend(argv) {
+  const parsed = parseAppendArgs(argv);
+  if (!parsed.ok) {
+    console.error(parsed.error);
+    return 1;
+  }
+
+  try {
+    const entry = appendAuditEntry(process.cwd(), parsed.options);
+    printJson(entry);
+    return 0;
+  } catch (error) {
+    console.error(error.message);
+    return 1;
+  }
+}
+
+function runAuditRead(argv) {
+  const parsed = parseReadArgs(argv);
+  if (!parsed.ok) {
+    console.error(parsed.error);
+    return 1;
+  }
+
+  try {
+    const entries = readAuditEntries(process.cwd(), parsed.options.taskId);
+    printJson({
+      schema_version: "0.3",
+      entries
+    });
+    return 0;
+  } catch (error) {
+    console.error(error.message);
+    return 1;
+  }
+}
+
+function parseAppendArgs(argv) {
+  const options = {
+    description: null,
+    event_type: null,
+    phase: null,
+    risk_at_time: "unknown",
+    signal: null,
+    task_id: null,
+    user_input: null
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (Object.hasOwn(FLAG_MAP, arg)) {
+      const key = FLAG_MAP[arg];
+      options[key] = argv[index + 1] ?? null;
+      index += 1;
+      continue;
+    }
+
+    return { ok: false, error: `未知参数: ${arg}` };
+  }
+
+  if (!options.task_id || !options.event_type || !options.phase || !options.signal || !options.description) {
+    return { ok: false, error: "需要 --task-id --event-type --phase --signal --description 参数" };
+  }
+
+  return { ok: true, options };
+}
+
+function parseReadArgs(argv) {
+  const taskIdFlagIndex = argv.indexOf("--task-id");
+  if (taskIdFlagIndex < 0 || !argv[taskIdFlagIndex + 1]) {
+    return { ok: false, error: "需要 --task-id 参数" };
+  }
+
+  if (argv.length !== 2) {
+    return { ok: false, error: "audit read 仅支持 --task-id <id>" };
+  }
+
+  return { ok: true, options: { taskId: argv[taskIdFlagIndex + 1] } };
+}
+
+function printJson(value) {
+  console.log(`${JSON.stringify(value, null, 2)}\n`);
+}
+
+const FLAG_MAP = {
+  "--description": "description",
+  "--event-type": "event_type",
+  "--phase": "phase",
+  "--risk-at-time": "risk_at_time",
+  "--signal": "signal",
+  "--task-id": "task_id",
+  "--user-input": "user_input"
+};