coding-agent-harness 1.0.4 → 1.0.5

package/docs-release/guides/agent-installation.en-US.md

@@ -185,26 +185,26 @@ The agent must read `session.json` and `migrate-plan.json`, then migrate active
 After initialization or migration, agents should not manually copy task folders. Use lifecycle commands:
 
 ```bash
-harness new-task phase-2-lifecycle \
+harness new-task \
   --title "Phase 2 task lifecycle" \
   --locale en-US \
   /path/to/project
 
-harness task-start phase-2-lifecycle \
+harness task-start <task-id-from-new-task-output> \
   --message "Start lifecycle slice implementation" \
   /path/to/project
 
-harness task-log phase-2-lifecycle \
+harness task-log <task-id-from-new-task-output> \
   --message "Completed CLI and template updates" \
   --evidence "command:TARGET:npm-test:passed" \
   /path/to/project
 
-harness review-confirm TASKS/phase-2-lifecycle \
+harness review-confirm <task-id-from-new-task-output> \
   --reviewer "Human Reviewer" \
-  --confirm phase-2-lifecycle \
+  --confirm <task-id-from-new-task-output> \
   /path/to/project
 
-harness task-complete phase-2-lifecycle \
+harness task-complete <task-id-from-new-task-output> \
   --message "Verification loop completed" \
   /path/to/project
 ```
@@ -212,13 +212,14 @@ harness task-complete phase-2-lifecycle \
 Rules:
 
 - Do not manually copy task templates or create partial task folders. `harness check` enforces the file set created by `new-task`.
+- `new-task --title "..."` generates a default ID like `YYYY-MM-DD-phase-2-task-lifecycle-a1b2c3d4` to reduce collisions when multiple people or agents create tasks in the same repository. Pass an explicit `<task-id>` only when a coordinator needs a stable compatibility ID.
 - `new-task --budget simple` creates `brief.md`, `task_plan.md`, `visual_map.md`, and `progress.md`.
 - `new-task` defaults to `standard` and creates the simple files plus `execution_strategy.md`, `findings.md`, `lesson_candidates.md`, and `review.md`.
 - `new-task --budget complex` creates the standard files plus `references/INDEX.md` and `artifacts/INDEX.md`.
 - Existing task directories are not overwritten. Renaming or continuing old tasks is a coordinator decision.
 - `task-start`, `task-block`, and `task-complete` only update lifecycle status and logs in `progress.md`.
 - `task-log` only appends execution records. Evidence uses `type:PATH:summary`, for example `command:TARGET:npm-test:passed`.
-- `review-confirm` appends a human review confirmation to `review.md` and a log entry to `progress.md`. It must reject open P0/P1/P2 findings marked `Open: yes` or `Blocks Release: yes`.
+- `review-confirm` writes human review confirmation audit fields to the task `INDEX.md` through gated commits. It must reject open P0/P1/P2 findings marked `Open: yes` or `Blocks Release: yes`.
 - CLI-owned lifecycle and lesson commands auto-commit allowlisted writes in a clean Git root. Dirty state appears in `status` / dashboard warnings and blocks those mechanical commits. Agent-owned manual edits still need proactive commits; deferred commits must record the no-commit reason, owner, and next step.
 - `status --json` keeps old `task.state` for compatibility and adds `lifecycleState`, `reviewStatus`, `closeoutStatus`, and `stateConflicts`. `done` means implementation finished; it does not mean `closed`.
 - For human operation, start the local HTML workbench with `harness dev /path/to/project`. It binds to `127.0.0.1`, chooses a port automatically, opens the browser, and refreshes when docs change. In headless or CI contexts, use `harness dev --no-open /path/to/project`.

package/docs-release/guides/agent-installation.md

@@ -204,26 +204,26 @@ harness migrate-verify \
 初始化或迁移完成后，agent 不应手工复制任务目录。使用生命周期命令创建和推进任务：
 
 ```bash
-harness new-task phase-2-lifecycle \
+harness new-task \
   --title "阶段二任务生命周期" \
   --locale zh-CN \
   /path/to/project
 
-harness task-start phase-2-lifecycle \
+harness task-start <new-task 输出的 task-id> \
   --message "开始实现生命周期切片" \
   /path/to/project
 
-harness task-log phase-2-lifecycle \
+harness task-log <new-task 输出的 task-id> \
   --message "完成 CLI 与模板更新" \
   --evidence "command:TARGET:npm-test:passed" \
   /path/to/project
 
-harness review-confirm TASKS/phase-2-lifecycle \
+harness review-confirm <new-task 输出的 task-id> \
   --reviewer "Human Reviewer" \
-  --confirm phase-2-lifecycle \
+  --confirm <new-task 输出的 task-id> \
   /path/to/project
 
-harness task-complete phase-2-lifecycle \
+harness task-complete <new-task 输出的 task-id> \
   --message "验证闭环完成" \
   /path/to/project
 ```
@@ -232,6 +232,8 @@ harness task-complete phase-2-lifecycle \
 
 - 不要手工复制任务模板，也不要创建不完整任务目录。`harness check` 会按
   `new-task` 创建的预算文件集校验。
+- `new-task --title "..."` 默认生成类似 `YYYY-MM-DD-phase-2-task-lifecycle-a1b2c3d4`
+  的任务 ID，避免多人或多 agent 同仓协作时重名；只有需要固定兼容 ID 时才传显式 `<task-id>`。
 - `new-task --budget simple` 创建 `brief.md`、`task_plan.md`、`visual_map.md`
   和 `progress.md`。
 - `new-task` 默认 `standard`，创建 simple 文件，并额外创建
@@ -242,7 +244,7 @@ harness task-complete phase-2-lifecycle \
 - `task-start`、`task-block`、`task-complete` 只更新 `progress.md` 的生命周期状态和日志。
 - `task-log` 只追加执行记录；证据使用 `type:PATH:summary`，例如
   `command:TARGET:npm-test:passed`。
-- `review-confirm` 会向 `review.md` 追加人工审查确认，并向 `progress.md` 追加日志；如果存在 `Open: yes` 或 `Blocks Release: yes` 的开放 P0/P1/P2 finding，必须拒绝确认。
+- `review-confirm` 会通过受控提交把人工确认审计字段写入任务 `INDEX.md`；如果存在 `Open: yes` 或 `Blocks Release: yes` 的开放 P0/P1/P2 finding，必须拒绝确认。
 - CLI-owned lifecycle 和 lesson 命令会在干净 Git root 中自动提交 allowlisted 写入；dirty 状态会出现在 `status` / dashboard 的警告里，并阻塞这些机械化提交。Agent 手工改动仍要主动提交，不能提交时记录 no-commit reason、owner 和下一步。
 - `status --json` 保留旧 `task.state` 用于兼容，并新增 `lifecycleState`、`reviewStatus`、`closeoutStatus` 和 `stateConflicts`。`done` 只表示实现完成，不等于 `closed`。
 - 人工操作入口使用本地 HTML workbench：`harness dev /path/to/project`。它会启动只绑定 `127.0.0.1` 的动态页面、自动选择端口、打开浏览器并随 docs 变更刷新。无 GUI 或 CI 场景使用 `harness dev --no-open /path/to/project`。

package/docs-release/guides/preset-development.md

@@ -28,6 +28,29 @@ and `harness install-user` seed them into the user preset root, while
 `harness preset seed` for the user root or `harness preset seed --project <target>`
 for the project root when a preset root is missing or incomplete.
 
+## Dashboard Management
+
+The Dashboard exposes a Presets view for the target project. Static dashboards
+show a read-only catalog of discovered project, user, and bundled presets,
+including source, purpose, compatible budgets, task kind, manifest path, and
+resource counts.
+
+Use the local dynamic Workbench when you want to manage presets from the web UI:
+
+```bash
+harness dev /path/to/project
+```
+
+In Workbench mode, the Presets view can check presets, install a local preset
+directory, `.zip` archive, or bundled preset id into the project or user scope,
+seed bundled presets into either scope, and uninstall project/user presets.
+Bundled package presets are immutable from the Dashboard: they can be inspected,
+checked, and used as install or seed sources, but not edited or deleted.
+
+The CLI and filesystem remain canonical. The Dashboard calls the same preset
+registry operations as `harness preset ...`; it does not store independent preset
+state.
+
 ## Package Layout
 
 ```text
@@ -184,13 +207,14 @@ Supported evidence types:
 ```bash
 harness preset check ./my-preset
 harness preset install ./my-preset
+harness preset install ./my-preset.zip
 harness preset install ./my-preset --project /path/to/project
 harness preset install legacy-migration --force
 harness preset seed
 harness preset seed --project /path/to/project
 harness preset list --json /path/to/project
 harness preset inspect custom-review --json /path/to/project
-harness new-task custom-review-task --preset custom-review --subject "API contracts" /path/to/project
+harness new-task --title "Custom review task" --preset custom-review --subject "API contracts" /path/to/project
 harness preset uninstall custom-review
 ```
 
@@ -199,7 +223,7 @@ harness preset uninstall custom-review
 For every preset, prove both the manifest and downstream task behavior:
 
 1. Run `harness preset check ./my-preset`.
-2. Install into an isolated HOME or disposable environment.
+2. Install the folder and, if distributing an archive, install the `.zip` into an isolated HOME or disposable environment.
 3. Create at least one task with `harness new-task --preset`.
 4. For reference bundles, create two different tasks from the same preset and verify both contain the same shared `references/` files and independent audit/evidence bundles.
 5. Run `harness status --json`, `harness task-index --json`, and `harness check --profile target-project <target>`.

package/docs-release/guides/task-state-machine.en-US.md

@@ -5,7 +5,8 @@ Chinese mirror: `docs-release/guides/task-state-machine.md`
 Coding Agent Harness does not model task state as a single field. The Dashboard derives the visible lifecycle from multiple files:
 
 - `progress.md` stores raw `task.state` and execution evidence.
-- `review.md` stores Agent Review Submission, material findings, and Human Review Confirmation.
+- `review.md` stores Agent Review Submission, material findings, and review evidence.
+- `INDEX.md` stores Task Audit Metadata, including task creation and human review confirmation audit fields.
 - `lesson_candidates.md` records lesson candidate decisions and sedimentation routing.
 - `10-WALKTHROUGH/Closeout-SSoT.md` records closeout status and links walkthrough evidence.
 - Tombstone / supersede metadata records whether a task was soft-deleted, merged, archived, or replaced.
@@ -32,20 +33,37 @@ stateDiagram-v2
   finalized --> [*]
 ```
 
-`task-review` means the agent submitted a review packet. It does not mean human approval. `review-confirm` is the Human Review Confirmation gate. `task-complete` / closeout is not a substitute for review confirmation.
+`task-review` means the agent submitted a review packet. It does not mean human approval. `review-confirm` is the human confirmation gate and writes its audit fields to `INDEX.md`. `task-complete` / closeout is not a substitute for review confirmation.
+
+## Phase Kind Map
+
+`visual_map.md` is the machine-readable phase timeline. New phase tables may include `Kind`, `Exit Command`, and `Actor` columns:
+
+| Kind | Purpose | Counts Toward Implementation Completion | Typical Exit |
+| --- | --- | --- | --- |
+| `init` | Scope, context, budget, and execution strategy. | no | `harness task-start <task-id>` |
+| `execution` | Implementation, documentation, and verification slices. | yes | `harness task-phase <task-id> <phase-id> --state done --completion 100 --evidence present` |
+| `gate` | Agent review submission, human confirmation, lesson routing, walkthrough, and closeout. | no | `harness task-review`, `harness review-confirm`, or `harness task-complete` |
+
+Older phase tables without `Kind` remain valid and are treated as `execution`.
+The Dashboard implementation score uses non-skipped `execution` phases only.
+Gate phases explain the next lifecycle action and owner; they do not make a finished implementation look incomplete.
+Agents may run `Exit Command` values with `Actor: agent`. `Actor: human` gates, especially `review-confirm`, require explicit human action.
 
 ## Derived State
 
 ```mermaid
 flowchart TB
   Progress["progress.md<br/>task.state + evidence"]
-  Review["review.md<br/>Agent Review Submission + findings + Human Review Confirmation"]
+  Index["INDEX.md<br/>Task Audit Metadata"]
+  Review["review.md<br/>Agent Review Submission + findings + evidence"]
   Lessons["lesson_candidates.md<br/>decision + sedimentation route"]
   Closeout["Closeout-SSoT.md<br/>closeout row + walkthrough"]
   Tombstone["tombstone / supersede metadata"]
   Scanner["scanner"]
 
   Progress --> Scanner
+  Index --> Scanner
   Review --> Scanner
   Lessons --> Scanner
   Closeout --> Scanner
@@ -62,7 +80,7 @@ flowchart TB
 | Field | Source | Purpose |
 | --- | --- | --- |
 | `task.state` | `progress.md` | Raw execution stage. |
-| `reviewStatus` | `review.md` + findings + Human Review Confirmation | Separates missing review, agent-submitted review, blockers, and human confirmation. |
+| `reviewStatus` | `INDEX.md` Task Audit Metadata + `review.md` findings/submission | Separates missing review, agent-submitted review, blockers, and human confirmation. |
 | `closeoutStatus` | `Closeout-SSoT.md` | Separates missing, pending, and closed closeout. |
 | `lifecycleState` | scanner-derived | Main Dashboard lifecycle meaning. |
 | `taskQueues[]` | scanner-derived | Which lifecycle queues include the task. A task can be visible in more than one governance queue. |
@@ -76,9 +94,9 @@ flowchart TB
 | Tombstone, superseded-by, archive, or abandoned marker exists | `soft-deleted-superseded` | Hidden by default, but preserved for audit and replacement tracing. |
 | Open P0-P2 finding, invalid transition, audit failure, or failed human-review gate | `blocked` | Cannot enter human confirmation until the blocker is fixed or waived. |
 | Standard / complex task is missing required files, sections, evidence, lesson decision, or review submission | `missing-materials` | Needs agent repair; not part of the human review queue. |
-| `task-review` was submitted, materials are ready, and Human Review Confirmation is missing | `review-submitted` | Truly waiting for human review. |
-| Human Review Confirmation exists, but closeout / ledger / lessons are not fully closed | `confirmed-finalization-pending` | Accountability moved to the reviewer, but governance closeout remains. |
-| Human Review Confirmation exists, and closeout / ledger / lesson routing are complete | `finalized` | Truly complete and traceable. |
+| `task-review` was submitted, materials are ready, and `INDEX.md` does not show human confirmation | `review-submitted` | Truly waiting for human review. |
+| `INDEX.md` shows human confirmation, but closeout / ledger / lessons are not fully closed | `confirmed-finalization-pending` | Accountability moved to the reviewer, but governance closeout remains. |
+| `INDEX.md` shows human confirmation, and closeout / ledger / lesson routing are complete | `finalized` | Truly complete and traceable. |
 | `task.state = blocked` without a review blocker | `active-blocked` | Execution is blocked. |
 | `task.state = in_progress` | `active` | Work is active. |
 | `task.state = planned/not_started` | `ready` | Work has not started; not in human review by default. |
@@ -91,9 +109,9 @@ flowchart TB
 | `required` | Review document exists, but the packet is not ready for human review. |
 | `submitted` | An agent submitted a review packet. This is not human confirmation. |
 | `blocked-open-findings` | There is an open P0-P2 finding or a finding that blocks release / confirmation. |
-| `confirmed` | `Human Review Confirmation` exists. |
+| `confirmed` | `INDEX.md` Task Audit Metadata has `Human Review Status: confirmed` and committed audit fields. |
 
-Agent self-review, subagent review, and coordinator review can only move a task toward `submitted`. Only `review-confirm` or an explicit Dashboard Workbench human confirmation writes `Human Review Confirmation`.
+Agent self-review, subagent review, and coordinator review can only move a task toward `submitted`. Only `review-confirm` or an explicit Dashboard Workbench human confirmation writes the confirmation audit fields in `INDEX.md`.
 
 ## Lifecycle Queues
 
@@ -167,16 +185,15 @@ sequenceDiagram
   else accepted
     API->>Lifecycle: confirmTaskReview()
     Lifecycle->>Lifecycle: verify clean Git state, identity, hooks, allowlist
-    Lifecycle->>Docs: write Human Review Confirmation
-    Lifecycle->>Docs: append review-confirm log
-    Lifecycle->>Lifecycle: commit allowlisted review/progress files
+    Lifecycle->>Docs: write confirmation fields to INDEX.md
+    Lifecycle->>Lifecycle: commit allowlisted INDEX.md
     Lifecycle->>Docs: record confirmation commit SHA + committed audit status
     API->>Scanner: regenerate dashboard snapshot
     API-->>UI: confirmed task
   end
 ```
 
-Strict rule: an agent can prepare review evidence and submit the task for review, but the task is not human-confirmed until the Human Review Confirmation block exists. Confirmation must use gated auto-commit: the CLI and Workbench reject dirty Git state, missing commit identity, hook/preflight failure, or writes outside the current task `review.md` / `progress.md` allowlist, and return recovery guidance.
+Strict rule: an agent can prepare review evidence and submit the task for review, but the task is not human-confirmed until the task `INDEX.md` contains committed confirmation audit fields. Confirmation must use gated auto-commit: the CLI and Workbench reject dirty Git state, missing commit identity, hook/preflight failure, or writes outside the current task `INDEX.md` allowlist, and return recovery guidance.
 
 CLI-owned mechanical writes and agent-owned manual slices have different boundaries. `new-task`, `task-*`, `task-phase`, `module-step`, `review-confirm`, `lesson-sediment`, and `lesson-promote --apply` acquire a lock, restrict writes to an allowlist, and auto-commit in a clean Git root. When an agent manually edits code, templates, or task docs, it still needs to proactively commit after verification; if it cannot commit, it must record the no-commit reason, owner, and next step, and must not mix unrelated dirty changes into the task commit.
 

package/docs-release/guides/task-state-machine.md

@@ -5,7 +5,8 @@ English mirror: `docs-release/guides/task-state-machine.en-US.md`
 Coding Agent Harness 的任务状态不是一个单字段。Dashboard 里看到的生命周期由多个文件共同推导：
 
 - `progress.md` 记录原始 `task.state` 和执行证据。
-- `review.md` 记录 Agent Review Submission、material findings 和 Human Review Confirmation。
+- `review.md` 记录 Agent Review Submission、material findings 和审查证据。
+- `INDEX.md` 记录任务审计元数据，包括任务创建和人工确认审计字段。
 - `lesson_candidates.md` 记录 lesson candidate 的人工判定和后续沉淀路由。
 - `10-WALKTHROUGH/Closeout-SSoT.md` 记录任务是否完成收口，并链接 walkthrough。
 - Tombstone / supersede 信息记录任务是否被软删除、合并、归档或替代。
@@ -32,20 +33,37 @@ stateDiagram-v2
   finalized --> [*]
 ```
 
-`task-review` 表示 Agent 提交审查材料包，不表示人工批准。`review-confirm` 才表示 Human Review Confirmation。`task-complete` / closeout 也不是 review confirmation 的替代品。
+`task-review` 表示 Agent 提交审查材料包，不表示人工批准。`review-confirm` 才表示人工确认门禁，并把审计字段写入 `INDEX.md`。`task-complete` / closeout 也不是 review confirmation 的替代品。
+
+## 阶段类型地图
+
+`visual_map.md` 是机器可读的阶段时间线。新的阶段表可以包含 `Kind`、`Exit Command` 和 `Actor` 三列：
+
+| Kind | 作用 | 是否计入实现完成度 | 典型出口 |
+| --- | --- | --- | --- |
+| `init` | 范围、上下文、预算和执行策略。 | 否 | `harness task-start <task-id>` |
+| `execution` | 实现、文档和验证切片。 | 是 | `harness task-phase <task-id> <phase-id> --state done --completion 100 --evidence present` |
+| `gate` | Agent 提交审查、人工确认、lesson routing、walkthrough 和 closeout。 | 否 | `harness task-review`、`harness review-confirm` 或 `harness task-complete` |
+
+旧阶段表没有 `Kind` 也继续有效，默认按 `execution` 处理。
+Dashboard 实现完成度只计算非 skipped 的 `execution` 阶段。
+Gate 阶段用于解释下一步生命周期动作和责任人，不会让已完成的实现看起来未完成。
+Agent 只能执行 `Actor: agent` 的 `Exit Command`。`Actor: human` 的 gate，尤其是 `review-confirm`，必须由人工明确执行。
 
 ## 派生状态
 
 ```mermaid
 flowchart TB
   Progress["progress.md<br/>task.state + evidence"]
-  Review["review.md<br/>Agent Review Submission + findings + Human Review Confirmation"]
+  Index["INDEX.md<br/>Task Audit Metadata"]
+  Review["review.md<br/>Agent Review Submission + findings + evidence"]
   Lessons["lesson_candidates.md<br/>decision + sedimentation route"]
   Closeout["Closeout-SSoT.md<br/>closeout row + walkthrough"]
   Tombstone["tombstone / supersede metadata"]
   Scanner["scanner"]
 
   Progress --> Scanner
+  Index --> Scanner
   Review --> Scanner
   Lessons --> Scanner
   Closeout --> Scanner
@@ -62,7 +80,7 @@ flowchart TB
 | 字段 | 来源 | 作用 |
 | --- | --- | --- |
 | `task.state` | `progress.md` | 原始执行阶段。 |
-| `reviewStatus` | `review.md` + findings + Human Review Confirmation | 区分缺审查、Agent 已提交审查、阻塞、人工确认。 |
+| `reviewStatus` | `INDEX.md` Task Audit Metadata + `review.md` findings/submission | 区分缺审查、Agent 已提交审查、阻塞、人工确认。 |
 | `closeoutStatus` | `Closeout-SSoT.md` | 区分收口缺失、待处理、已关闭。 |
 | `lifecycleState` | scanner 派生 | Dashboard 的主生命周期语义。 |
 | `taskQueues[]` | scanner 派生 | 任务属于哪些生命周期队列。一个任务可同时在多个治理队列中可见。 |
@@ -76,9 +94,9 @@ flowchart TB
 | 有 tombstone、superseded-by、archive 或 abandoned 标记 | `soft-deleted-superseded` | 默认隐藏，但保留审计和替代链。 |
 | 有 open P0-P2 finding、非法状态转换、审计失败或人审门禁失败 | `blocked` | 不能进入人工确认，必须先修 blocker 或记录 waiver。 |
 | 标准/复杂任务缺必需文件、章节、证据、lesson decision 或 review submission | `missing-materials` | 需要 Agent 补材料，不属于人审队列。 |
-| 已执行 `task-review`，材料齐全，且未 Human Review Confirmation | `review-submitted` | 真正等待人审。 |
-| 已 Human Review Confirmation，但 closeout / ledger / lessons 仍未全部收口 | `confirmed-finalization-pending` | 责任已转移给确认人，但治理收口仍待完成。 |
-| 已 Human Review Confirmation，且 closeout / ledger / lesson routing 完成 | `finalized` | 真正完成，可只读追溯。 |
+| 已执行 `task-review`，材料齐全，且 `INDEX.md` 尚未显示人工确认 | `review-submitted` | 真正等待人审。 |
+| `INDEX.md` 已显示人工确认，但 closeout / ledger / lessons 仍未全部收口 | `confirmed-finalization-pending` | 责任已转移给确认人，但治理收口仍待完成。 |
+| `INDEX.md` 已显示人工确认，且 closeout / ledger / lesson routing 完成 | `finalized` | 真正完成，可只读追溯。 |
 | `task.state = blocked` 但没有 review blocker | `active-blocked` | 执行阻塞。 |
 | `task.state = in_progress` | `active` | 执行中。 |
 | `task.state = planned/not_started` | `ready` | 准备中，默认不进入人审队列。 |
@@ -91,9 +109,9 @@ flowchart TB
 | `required` | 有 review 文档，但还没有足够材料可提交人审。 |
 | `submitted` | Agent 已提交审查材料包；这不是人工确认。 |
 | `blocked-open-findings` | 有 open P0-P2 finding，或 finding 阻塞发布 / 确认。 |
-| `confirmed` | 已写入 `Human Review Confirmation`。 |
+| `confirmed` | `INDEX.md` Task Audit Metadata 包含 `Human Review Status: confirmed` 和已提交审计字段。 |
 
-Agent 自查、subagent 审查和 coordinator 审查都只能让任务接近 `submitted`。只有 `review-confirm` 或 Workbench 的明确人工确认动作会写入 `Human Review Confirmation`。
+Agent 自查、subagent 审查和 coordinator 审查都只能让任务接近 `submitted`。只有 `review-confirm` 或 Workbench 的明确人工确认动作会把确认审计字段写入 `INDEX.md`。
 
 ## 生命周期队列
 
@@ -174,16 +192,15 @@ sequenceDiagram
   else accepted
     API->>Lifecycle: confirmTaskReview()
     Lifecycle->>Lifecycle: verify Git clean, identity, hooks, allowlist
-    Lifecycle->>Docs: write Human Review Confirmation
-    Lifecycle->>Docs: append review-confirm log
-    Lifecycle->>Lifecycle: commit allowlisted review/progress files
+    Lifecycle->>Docs: write confirmation fields to INDEX.md
+    Lifecycle->>Lifecycle: commit allowlisted INDEX.md
     Lifecycle->>Docs: record confirmation commit SHA + committed audit status
     API->>Scanner: regenerate dashboard snapshot
     API-->>UI: confirmed task
   end
 ```
 
-严格规则：Agent 可以准备 review evidence，也可以提交审查；但任务只有在 Human Review Confirmation block 存在后，才算人工确认。确认动作必须通过 gated auto-commit：Git 状态不干净、提交身份缺失、hook/preflight 失败，或待写文件超出当前任务 `review.md` / `progress.md` 白名单时，CLI 和 Workbench 都会拒绝并返回恢复建议。
+严格规则：Agent 可以准备 review evidence，也可以提交审查；但任务只有在任务 `INDEX.md` 包含已提交的确认审计字段后，才算人工确认。确认动作必须通过 gated auto-commit：Git 状态不干净、提交身份缺失、hook/preflight 失败，或待写文件超出当前任务 `INDEX.md` 白名单时，CLI 和 Workbench 都会拒绝并返回恢复建议。
 
 CLI-owned 机械写入和 agent-owned 手工切片是两条边界。`new-task`、`task-*`、`task-phase`、`module-step`、`review-confirm`、`lesson-sediment` 和 `lesson-promote --apply` 会在干净 Git root 中加锁、限制写入范围并自动提交。Agent 手工编辑代码、模板或任务文档时仍要在验证后主动提交；无法提交时必须记录 no-commit reason、owner 和下一步，不能把 unrelated dirty changes 混入任务提交。
 

package/examples/minimal-project/docs/09-PLANNING/TASKS/demo-task/INDEX.md

@@ -0,0 +1,60 @@
+# Demo task - Task Package Index
+
+Task Contract: harness-task/v1
+
+## Task Identity
+
+| Field | Value |
+| --- | --- |
+| Task ID | `demo-task` |
+| Budget | `standard` |
+| Preset | `none` |
+| Module | `n/a` |
+| Long-running | `no` |
+| Created | 2026-05-25 |
+
+## Task Audit Metadata
+
+| Field | Value |
+| --- | --- |
+| Created By | historical-backfill |
+| Created At | 2026-05-25 |
+| Command Shape | n/a |
+| Budget | standard |
+| Template Source | examples/minimal-project historical fixture |
+| Task Creator | n/a |
+| Task Creator Source | legacy-unavailable |
+| Human Review Status | not-confirmed |
+| Confirmation ID | n/a |
+| Confirmed At | n/a |
+| Reviewer | n/a |
+| Reviewer Email | n/a |
+| Confirm Text | n/a |
+| Evidence Checked | n/a |
+| Review Commit SHA | n/a |
+| Audit Source | migrated-legacy-scaffold |
+| Audit Status | migrated |
+| Exception Reason | Existing demo task predates scaffold provenance enforcement. |
+| Message | n/a |
+| Migration Status | migrated |
+| Migrated From | brief.md#Scaffold Provenance |
+| Legacy Extra Fields | {} |
+| Migration Notes | example fixture backfilled to INDEX audit metadata |
+
+## Core Contract Files
+
+| File | Purpose |
+| --- | --- |
+| `brief.md` | Human-readable task summary and context entry. |
+| `task_plan.md` | Current task goal, scope, selected budget, acceptance, and operating decisions. |
+| `visual_map.md` | Phase map, evidence status, next lifecycle commands, and supporting diagrams. |
+| `progress.md` | Execution log, verification evidence, decisions, and handoff notes. |
+
+## Standard Task Files
+
+| File | Purpose |
+| --- | --- |
+| `execution_strategy.md` | Execution mode, ownership, conflict control, and evidence strategy. |
+| `findings.md` | Findings, research notes, accepted risks, and unresolved questions. |
+| `lesson_candidates.md` | Task-local lesson candidate decisions before closeout. |
+| `review.md` | Agent review submission, adversarial review, findings, evidence, and routing. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "coding-agent-harness",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "Document governance kernel for long-running coding agents.",
   "type": "module",
   "keywords": [
@@ -44,6 +44,7 @@
     "CHANGELOG.md",
     "SKILL.md",
     "LICENSE",
+    "LICENSE-EXCEPTION.md",
     "references/",
     "skills/",
     "presets/",
@@ -56,5 +57,5 @@
   "engines": {
     "node": ">=18"
   },
-  "license": "MIT"
+  "license": "AGPL-3.0-or-later"
 }

package/references/harness-ledger.md

@@ -48,7 +48,7 @@ Harness Ledger 不记录：
 触发任务生命周期变化时，优先使用 CLI：
 
 ```bash
-harness new-task <task-id>
+harness new-task --title "<title>"
 harness task-start <task-id>
 harness task-phase <task-id> <phase-id> --state done
 harness task-review <task-id>

package/scripts/commands/migration-command.mjs

@@ -3,8 +3,38 @@ import {
   runMigration,
   verifyMigrationSession,
 } from "../lib/harness-core.mjs";
+import {
+  applyTaskAuditIndexMigration,
+  planTaskAuditIndexMigration,
+} from "../lib/task-audit-migration.mjs";
 
 export function runMigrationCommand(command, { args, takeFlag, takeOption, targetArg }) {
+  if (command === "migrate-task-audit-index") {
+    const json = takeFlag("--json");
+    const apply = takeFlag("--apply");
+    const planOnly = takeFlag("--plan");
+    try {
+      const result = apply && !planOnly
+        ? applyTaskAuditIndexMigration(targetArg())
+        : planTaskAuditIndexMigration(targetArg());
+      if (json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.log(`Task audit INDEX migration ${result.result}: ${result.target}`);
+        console.log(`actions: ${result.summary.actions}`);
+        console.log(`legacy audit blocks: ${result.summary.legacyAuditBlocks}`);
+        console.log(`failures: ${result.summary.failures}`);
+        for (const action of result.actions || []) console.log(`- ${action.taskId}: ${action.legacyBlocks.join(", ")}`);
+        for (const failure of result.failures || []) console.error(`Failure: ${failure.taskId}: ${failure.failure}`);
+      }
+      process.exit(result.failures?.length ? 1 : 0);
+    } catch (error) {
+      if (json && error.plan) console.error(JSON.stringify(error.plan, null, 2));
+      else console.error(error.message);
+      process.exit(1);
+    }
+  }
+
   if (command === "migrate-plan") {
     const json = takeFlag("--json");
     const limit = Number.parseInt(takeOption("--limit", "20"), 10) || 20;

package/scripts/commands/task-command.mjs

@@ -1,4 +1,3 @@
-import fs from "node:fs";
 import {
   confirmTaskReview,
   createTask,
@@ -28,12 +27,7 @@ export function runTaskCommand(command, { args, takeFlag, takeOption, targetArg
     const longRunning = takeFlag("--long-running");
     try {
       const parsed = parseNewTaskArgs(args, { preset, fromSession });
-      const taskId = parsed.taskId;
-      if (!taskId) {
-        console.error("Missing task id");
-        process.exit(2);
-      }
-      console.log(JSON.stringify(createTask(parsed.target, taskId, { title, locale, dryRun, moduleKey, budget, longRunning, preset, fromSession, presetArgs: parsed.presetArgs }), null, 2));
+      console.log(JSON.stringify(createTask(parsed.target, parsed.taskId, { title, locale, dryRun, moduleKey, budget, longRunning, preset, fromSession, presetArgs: parsed.presetArgs, automaticTaskId: parsed.automaticTaskId }), null, 2));
     } catch (error) {
       console.error(error.message);
       process.exit(1);
@@ -229,20 +223,15 @@ export function runTaskCommand(command, { args, takeFlag, takeOption, targetArg
   throw new Error(`Unsupported task command: ${command}`);
 }
 
-function parseNewTaskArgs(args, { preset = "", fromSession = "" } = {}) {
+function parseNewTaskArgs(args, { preset = "" } = {}) {
   const values = [...args];
-  let taskId = "";
-  if (!fromSession) {
-    taskId = values.shift() || "";
-  } else if (values.length > 0 && !values[0].startsWith("-") && !(values.length === 1 && fs.existsSync(values[0]))) {
-    taskId = values.shift();
-  }
   const presetPackage = preset ? readPresetPackageForNewTask(preset, values) : null;
-  if (!taskId && fromSession) taskId = presetPackage?.task?.defaultTaskId || "harness-v1-migration";
-  const parsed = splitPresetArgsAndTarget(values, presetPackage);
+  const parsed = splitPresetArgsAndPositionals(values, presetPackage);
+  const resolved = resolveNewTaskPositionals(parsed.positionals);
   return {
-    taskId,
-    target: parsed.target || ".",
+    taskId: resolved.taskId,
+    target: resolved.target || ".",
+    automaticTaskId: !resolved.taskId,
     presetArgs: parsed.presetArgs,
   };
 }
@@ -275,9 +264,9 @@ function presetDiscoveryTargetCandidates(values) {
   return candidates;
 }
 
-function splitPresetArgsAndTarget(values, presetPackage) {
+function splitPresetArgsAndPositionals(values, presetPackage) {
   const presetArgs = [];
-  const targetCandidates = [];
+  const positionals = [];
   const declaredFlags = new Map(Object.values(presetPackage?.inputs || {}).filter((input) => input.flag).map((input) => [input.flag, input]));
   for (let index = 0; index < values.length; index += 1) {
     const value = values[index];
@@ -295,18 +284,30 @@ function splitPresetArgsAndTarget(values, presetPackage) {
         index += 1;
       }
     } else {
-      targetCandidates.push(value);
+      positionals.push(value);
     }
   }
-  if (targetCandidates.length > 1) {
-    throw new Error(`Too many positional arguments for new-task: ${targetCandidates.join(", ")}`);
-  }
   return {
-    target: targetCandidates[0] || "",
+    positionals,
     presetArgs,
   };
 }
 
+function isPathLikePositional(value) {
+  return value === "." || value === ".." || value.startsWith("/") || value.startsWith("~/") || value.includes("/") || value.includes("\\");
+}
+
+function resolveNewTaskPositionals(positionals) {
+  if (positionals.length === 0) return { taskId: "", target: "" };
+  if (positionals.length === 1) {
+    const [value] = positionals;
+    if (isPathLikePositional(value)) return { taskId: "", target: value };
+    return { taskId: value, target: "" };
+  }
+  if (positionals.length === 2) return { taskId: positionals[0], target: positionals[1] };
+  throw new Error(`Too many positional arguments for new-task: ${positionals.join(", ")}`);
+}
+
 function formatTaskCommandError(error) {
   const lines = [error.message];
   if (Array.isArray(error.recovery) && error.recovery.length > 0) {

package/scripts/harness.mjs

@@ -87,16 +87,17 @@ Usage:
   harness init [--dry-run] [--locale zh-CN|en-US] [--capabilities core,dashboard] [--add-npm-scripts] [target]
   harness add-capability <name> [--dry-run] [--locale zh-CN|en-US] [target]
   harness migrate-plan [--json] [--limit n] [target]
+  harness migrate-task-audit-index [--plan] [--apply] [--json] [target]
   harness migrate-run [--locale zh-CN|en-US] [--assume-locale] [--allow-dirty] [--plan-only] [--out-dir folder] [--session-dir folder] [target]
   harness migrate-verify [--json] [--full-cutover] <session.json>
   harness governance rebuild [--dry-run] [--archive] [--apply] [target]
   harness preset list [--json] [target]
   harness preset inspect <id> [--json] [target]
   harness preset check <id> [--json] [target]
-  harness preset install <path-or-builtin-id> [--project] [--force] [--json] [target]
+  harness preset install <folder|zip|builtin-id> [--project] [--force] [--json] [target]
   harness preset seed [--project] [--force] [--dry-run] [--json] [target]
   harness preset uninstall <id> [--project] [--json] [target]
-  harness new-task <task-id> [--module key] [--budget simple|standard|complex] [--preset id] [--from-session session.json] [--long-running] [--title title] [--locale zh-CN|en-US] [--dry-run] [target]
+  harness new-task [task-id] [--module key] [--budget simple|standard|complex] [--preset id] [--from-session session.json] [--long-running] [--title title] [--locale zh-CN|en-US] [--dry-run] [target]
   harness task-start <task-id> [--message text] [target]
   harness task-phase <task-id> <phase-id> [--state done] [--completion 100] [--evidence present] [target]
   harness task-log <task-id> --message text [--evidence type:PATH:summary] [target]
@@ -127,6 +128,9 @@ Preset discovery:
   "harness init" seeds bundled presets into the target project. "harness
   install-user" and npm postinstall seed bundled presets into the user root.
   Use "harness preset seed" to repair or re-run preset seeding.
+  Use "harness preset install" with a local preset folder, .zip archive, or
+  bundled preset id. Preset archives must contain preset.yaml at the archive
+  root or inside one top-level folder.
   Use "harness preset list --json" to see available presets, their source,
   purpose, compatible budgets, and manifest path. Use "harness preset inspect
   <id> --json" for the full preset manifest summary.
@@ -224,7 +228,7 @@ if (command === "help" || command === "--help" || command === "-h") {
     console.error(error.message);
     process.exit(1);
   }
-} else if (["migrate-plan", "migrate-run", "migrate-verify"].includes(command)) {
+} else if (["migrate-plan", "migrate-run", "migrate-verify", "migrate-task-audit-index"].includes(command)) {
   runMigrationCommand(command, { args, takeFlag, takeOption, targetArg });
 } else if (command === "governance") {
   const subcommand = args.shift() || "";