coding-agent-harness 1.0.4 → 1.0.5

package/templates/dashboard/assets/i18n.js

@@ -7,6 +7,8 @@ window.HarnessI18n = {
     "reviewQueue": "Lifecycle Queue Workbench",
     "moduleView": "Modules",
     "readiness": "Readiness",
+    "snapshotStatus": "Snapshot status",
+    "snapshot": "Snapshot",
     "tasks": "Tasks",
     "blockers": "Blockers",
     "advice": "Advice",
@@ -23,6 +25,7 @@ window.HarnessI18n = {
     "missingBriefs": "tasks still need human visibility briefs.",
     "reviewAdvice": "Continue, but keep adoption advice visible.",
     "noBlockers": "No blockers in this snapshot.",
+    "snapshotNotValidated": "Snapshot only; run validated status before release decisions.",
     "firstLook": "First look",
     "projectFlow": "Project Flow",
     "projectProgress": "Project Progress",
@@ -132,6 +135,7 @@ window.HarnessI18n = {
     "state_pass": "pass",
     "state_warn": "warn",
     "state_fail": "fail",
+    "state_snapshot": "snapshot",
     "state_in_progress": "in progress",
     "state_planned": "planned",
     "state_review": "review",
@@ -263,7 +267,72 @@ window.HarnessI18n = {
     "reviewConfirmTextMismatch": "Type the task id shown in the input hint.",
     "reviewSubmitting": "Submitting review confirmation...",
     "reviewCompleteSuccess": "Review confirmed. Reloading snapshot...",
-    "reviewCompleteFailed": "Review confirmation failed"
+    "reviewCompleteFailed": "Review confirmation failed",
+    "presetCatalog": "Presets",
+    "presetCatalogSubtitle": "Manage project, user, and bundled task method packages. Precedence is project first, then user, then bundled.",
+    "presetSearch": "Search presets",
+    "presetSearchPlaceholder": "Search id, purpose, kind, source, or path",
+    "presetSourceFilter": "Preset source filter",
+    "allPresets": "All",
+    "presetSourceProject": "Project",
+    "presetSourceUser": "User",
+    "presetSourceBuiltin": "Builtin",
+    "presetSource_project": "Project",
+    "presetSource_user": "User",
+    "presetSource_builtin": "Builtin",
+    "presetEffective": "Effective",
+    "presetShadowed": "Shadowed",
+    "presetSources": "Preset Sources",
+    "presetSourcesHint": "Roots are read in precedence order. Higher layers override lower layers with the same id.",
+    "presetPriorityTitle": "Preset precedence",
+    "presetCollection": "Preset collection",
+    "presetCollectionHint": "Select a preset to inspect its manifest and actions.",
+    "presetLayerStack": "Layer stack for this id",
+    "presetLayerStackHint": "Project presets override user presets. User presets override bundled presets.",
+    "presetContextActions": "Selected preset actions",
+    "presetCheckHint": "Validate the currently selected preset manifest.",
+    "presetShadowedActionHint": "This layer is shadowed. CLI check and inspect commands resolve the effective preset by id, so they are disabled here.",
+    "presetCheckSelected": "Check selected preset",
+    "presetUninstallSelected": "Uninstall selected layer",
+    "presetUninstallHint": "Scope is locked to the selected project or user layer.",
+    "presetBuiltinImmutable": "Bundled presets are package defaults and cannot be uninstalled.",
+    "presetImportTitle": "Import preset",
+    "presetImportHint": "Install a local folder, .zip archive, or bundled preset id into a project or user layer.",
+    "presetRestoreBundled": "Restore bundled presets",
+    "presetRestoreBundledHint": "Copies bundled presets into the selected local layer. CLI name: preset seed.",
+    "presetCommandsEffectiveOnly": "CLI inspect/check commands resolve the effective preset by id. This shadowed layer is shown for comparison only.",
+    "noPresets": "No presets found.",
+    "version": "Version",
+    "manifestVersion": "Manifest version",
+    "manifestPath": "Manifest path",
+    "source": "Source",
+    "scope": "Scope",
+    "taskKind": "Task kind",
+    "budgets": "Budgets",
+    "inputs": "Inputs",
+    "writeScopes": "Write scopes",
+    "requiredReads": "Required reads",
+    "presetActions": "Preset Actions",
+    "presetWorkbenchRequired": "Use the dynamic workbench to manage presets. Static snapshots are read-only.",
+    "presetCheck": "Check preset",
+    "presetInstall": "Install preset",
+    "presetSeed": "Restore bundled presets",
+    "presetUninstall": "Uninstall preset",
+    "presetInstallSourcePlaceholder": "Local folder, .zip, or bundled preset id",
+    "forceOverwrite": "Force overwrite",
+    "confirmPresetId": "Confirm preset id",
+    "copyPresetId": "Copy preset ID",
+    "copyIdShort": "Copy ID",
+    "copyCommand": "Copy command",
+    "useSelectedId": "Use selected ID",
+    "presetConfirmRequired": "Use the selected ID before uninstalling.",
+    "presetActionRunning": "Running preset action",
+    "presetActionSuccess": "Preset action completed",
+    "presetActionFailed": "Preset action failed",
+    "created": "created",
+    "skipped": "skipped",
+    "removed": "removed",
+    "notInstalled": "not installed"
   },
   "zh": {
     "eyebrow": "Coding Agent Harness 控制台",
@@ -273,6 +342,8 @@ window.HarnessI18n = {
     "reviewQueue": "生命周期队列工作台",
     "moduleView": "模块",
     "readiness": "发布状态",
+    "snapshotStatus": "快照状态",
+    "snapshot": "快照",
     "tasks": "任务",
     "blockers": "阻塞",
     "advice": "建议",
@@ -289,6 +360,7 @@ window.HarnessI18n = {
     "missingBriefs": "个任务缺少给人看的 brief。",
     "reviewAdvice": "可以继续，但升级建议必须保持可见。",
     "noBlockers": "当前快照没有阻塞项。",
+    "snapshotNotValidated": "这里只是快照；发布决策前请运行完整验证状态。",
     "firstLook": "第一眼",
     "projectFlow": "项目流程图",
     "projectProgress": "项目进度",
@@ -391,6 +463,7 @@ window.HarnessI18n = {
     "state_pass": "通过",
     "state_warn": "警告",
     "state_fail": "失败",
+    "state_snapshot": "快照",
     "state_in_progress": "进行中",
     "state_planned": "计划中",
     "state_review": "审查中",
@@ -529,6 +602,71 @@ window.HarnessI18n = {
     "reviewConfirmTextMismatch": "请输入提示中的任务 ID。",
     "reviewSubmitting": "正在提交审查确认...",
     "reviewCompleteSuccess": "审查已确认，正在刷新快照...",
-    "reviewCompleteFailed": "审查确认失败"
+    "reviewCompleteFailed": "审查确认失败",
+    "presetCatalog": "Preset",
+    "presetCatalogSubtitle": "管理项目级、用户级和内置任务方法包。优先级是项目级、用户级、内置。",
+    "presetSearch": "搜索 preset",
+    "presetSearchPlaceholder": "搜索 ID、用途、类型、来源或路径",
+    "presetSourceFilter": "Preset 来源筛选",
+    "allPresets": "全部",
+    "presetSourceProject": "项目级",
+    "presetSourceUser": "用户级",
+    "presetSourceBuiltin": "内置",
+    "presetSource_project": "项目级",
+    "presetSource_user": "用户级",
+    "presetSource_builtin": "内置",
+    "presetEffective": "生效",
+    "presetShadowed": "被覆盖",
+    "presetSources": "Preset 来源",
+    "presetSourcesHint": "系统按优先级读取来源；同名时高优先级会覆盖低优先级。",
+    "presetPriorityTitle": "Preset 优先级",
+    "presetCollection": "Preset 列表",
+    "presetCollectionHint": "选择一个 preset，查看 manifest 详情和可用操作。",
+    "presetLayerStack": "同名层级",
+    "presetLayerStackHint": "项目级覆盖用户级，用户级覆盖内置。",
+    "presetContextActions": "当前 preset 操作",
+    "presetCheckHint": "校验当前选中的 preset manifest。",
+    "presetShadowedActionHint": "当前层级已被覆盖。CLI 检查和详情命令会按 ID 解析到生效 preset，因此这里禁用。",
+    "presetCheckSelected": "检查当前 preset",
+    "presetUninstallSelected": "卸载当前层级",
+    "presetUninstallHint": "范围会锁定到当前选中的项目级或用户级层。",
+    "presetBuiltinImmutable": "内置 preset 是包默认内容，不能卸载。",
+    "presetImportTitle": "导入 preset",
+    "presetImportHint": "把本地文件夹、.zip 压缩包或内置 preset ID 安装到项目级或用户级。",
+    "presetRestoreBundled": "恢复内置 preset",
+    "presetRestoreBundledHint": "把包内置 presets 写入选中的本地层级。CLI 名称是 preset seed。",
+    "presetCommandsEffectiveOnly": "CLI 详情/检查命令会按 ID 解析到生效 preset；当前被覆盖层只用于对比查看。",
+    "noPresets": "没有找到 preset。",
+    "version": "版本",
+    "manifestVersion": "Manifest 版本",
+    "manifestPath": "Manifest 路径",
+    "source": "来源",
+    "scope": "范围",
+    "taskKind": "任务类型",
+    "budgets": "预算",
+    "inputs": "输入项",
+    "writeScopes": "写入范围",
+    "requiredReads": "必读引用",
+    "presetActions": "Preset 操作",
+    "presetWorkbenchRequired": "管理 preset 需要使用动态 workbench；静态快照只读。",
+    "presetCheck": "检查 preset",
+    "presetInstall": "安装 preset",
+    "presetSeed": "恢复内置 preset",
+    "presetUninstall": "卸载 preset",
+    "presetInstallSourcePlaceholder": "本机文件夹、.zip 或内置 preset ID",
+    "forceOverwrite": "强制覆盖",
+    "confirmPresetId": "确认 preset ID",
+    "copyPresetId": "复制 preset ID",
+    "copyIdShort": "复制 ID",
+    "copyCommand": "复制命令",
+    "useSelectedId": "使用当前 ID",
+    "presetConfirmRequired": "卸载前请先使用当前 ID 完成确认。",
+    "presetActionRunning": "正在执行 preset 操作",
+    "presetActionSuccess": "Preset 操作完成",
+    "presetActionFailed": "Preset 操作失败",
+    "created": "已创建",
+    "skipped": "已跳过",
+    "removed": "已移除",
+    "notInstalled": "未安装"
   }
 };

package/templates/planning/INDEX.md

@@ -0,0 +1,87 @@
+# {{TASK_TITLE}} - Task Package Index
+
+Task Contract: harness-task/v1
+
+## Task Identity
+
+| Field | Value |
+| --- | --- |
+| Task ID | `{{TASK_ID}}` |
+| Budget | `{{TASK_BUDGET}}` |
+| Preset | `{{TASK_PRESET}}` |
+| Module | `{{TASK_MODULE}}` |
+| Long-running | `{{TASK_LONG_RUNNING}}` |
+| Created | {{DATE}} |
+
+## Task Audit Metadata
+
+| Field | Value |
+| --- | --- |
+| Created By | {{TASK_AUDIT_CREATED_BY}} |
+| Created At | {{TASK_AUDIT_CREATED_AT}} |
+| Command Shape | {{TASK_AUDIT_COMMAND_SHAPE}} |
+| Budget | {{TASK_AUDIT_BUDGET}} |
+| Template Source | {{TASK_AUDIT_TEMPLATE_SOURCE}} |
+| Task Creator | {{TASK_AUDIT_TASK_CREATOR}} |
+| Task Creator Source | {{TASK_AUDIT_TASK_CREATOR_SOURCE}} |
+| Human Review Status | {{TASK_AUDIT_HUMAN_REVIEW_STATUS}} |
+| Confirmation ID | {{TASK_AUDIT_CONFIRMATION_ID}} |
+| Confirmed At | {{TASK_AUDIT_CONFIRMED_AT}} |
+| Reviewer | {{TASK_AUDIT_REVIEWER}} |
+| Reviewer Email | {{TASK_AUDIT_REVIEWER_EMAIL}} |
+| Confirm Text | {{TASK_AUDIT_CONFIRM_TEXT}} |
+| Evidence Checked | {{TASK_AUDIT_EVIDENCE_CHECKED}} |
+| Review Commit SHA | {{TASK_AUDIT_REVIEW_COMMIT_SHA}} |
+| Audit Source | {{TASK_AUDIT_AUDIT_SOURCE}} |
+| Audit Status | {{TASK_AUDIT_AUDIT_STATUS}} |
+| Exception Reason | {{TASK_AUDIT_EXCEPTION_REASON}} |
+| Message | {{TASK_AUDIT_MESSAGE}} |
+| Migration Status | {{TASK_AUDIT_MIGRATION_STATUS}} |
+| Migrated From | {{TASK_AUDIT_MIGRATED_FROM}} |
+| Legacy Extra Fields | {{TASK_AUDIT_LEGACY_EXTRA_FIELDS}} |
+| Migration Notes | {{TASK_AUDIT_MIGRATION_NOTES}} |
+
+## 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
+
+These files exist for standard and complex tasks.
+
+| 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. |
+
+## Optional Indexes
+
+| Index | Purpose |
+| --- | --- |
+| `references/INDEX.md` | References and preset-provided required reads. |
+| `artifacts/INDEX.md` | Generated outputs, evidence bundles, screenshots, reports, and command artifacts. |
+
+## Preset Summary
+
+This section is system-rendered. Presets may not add custom root-level files or arbitrary root `INDEX.md` content.
+
+| Field | Value |
+| --- | --- |
+| Preset | `{{TASK_PRESET}}` |
+| Preset Version | `{{TASK_PRESET_VERSION}}` |
+| Evidence Bundle | `{{TASK_EVIDENCE_BUNDLE}}` |
+| Resource Indexes | `references/INDEX.md`; `artifacts/INDEX.md` |
+
+## Update Rules
+
+- Update status and decisions in `progress.md`.
+- Keep task-specific goals and acceptance in `task_plan.md`.
+- Put large command output, screenshots, reports, and generated files in `artifacts/INDEX.md`.
+- Put source material, external links, and preset required reads in `references/INDEX.md`.

package/templates/planning/brief.md

@@ -24,7 +24,7 @@ State the user-visible or project-visible result this task must deliver.
 
 - Owner: coordinator
 - Lifecycle state: not_started
-- Required files: `task_plan.md`, `execution_strategy.md`, `visual_map.md`, `progress.md`, `findings.md`, `review.md`
+- Required files: `INDEX.md`, `task_plan.md`, `execution_strategy.md`, `visual_map.md`, `progress.md`, `findings.md`, `review.md`
 - Required closeout: verification evidence recorded in `progress.md`
 
 ## First Next Step

package/templates/planning/module_session_prompt.md

@@ -34,6 +34,7 @@ Do not edit shared SSoT files, coordinator-owned integration files, or unrelated
 
 - Keep `task.state`, `lifecycleState`, `reviewStatus`, and `closeoutStatus` separate when reporting progress.
 - `done` means the implementation step finished. It is not `closed` until closeout evidence is recorded.
+- Use the current task `visual_map.md` phase table as the lifecycle map. At the end of a slice, inspect the current gate phase and follow its `Exit Command` only when its `Actor` is `agent`.
 - If review is required, update `review.md`. Human review completion must be confirmed through the local dashboard workbench or by the coordinator with `harness review-confirm`; do not mark it complete while open P0/P1/P2 findings remain.
 
 ## Shared Sync Rule

package/templates/planning/review.md

@@ -61,24 +61,6 @@ Do not keep sample findings. If there are no material findings, leave only the h
 
 [If no material findings remain, state what evidence was checked and why no material finding remains.]
 
-## Human Review Confirmation
-
-This section must only be completed by a human reviewer or by a command/workbench action acting on explicit human confirmation. Agent review submission, self-review, and subagent review do not satisfy this gate.
-
-| Field | Value |
-| --- | --- |
-| Confirmation ID | [generated by review-confirm] |
-| Confirmed At | [timestamp] |
-| Reviewer | [human name] |
-| Reviewer Email | [email, if available] |
-| Task Key | {{TASK_ID}} |
-| Confirm Text | [must match the task id or confirmation phrase required by the command] |
-| Evidence Checked | [review packet / tests / diff summary] |
-| Commit SHA | [confirmation commit SHA generated by review-confirm] |
-| Audit Status | committed / blocked |
-
-Do not fill this section when the task still belongs in Missing Materials, Blocked, or Lessons routing. `review-confirm` and the Dashboard Workbench must reject dirty Git state, missing commit identity, hook failures, or writes outside the current task `review.md` / `progress.md` allowlist.
-
 ## Evidence Checked
 
 | Evidence ID | Type | Path | Summary |

package/templates/planning/task_plan.md

@@ -1,6 +1,7 @@
 # [Task Name]
 
 Task Contract: harness-task/v1
+Task Package Index: required
 
 ## Goal
 
@@ -11,58 +12,18 @@ Task Contract: harness-task/v1
 - In scope: [specific files, modules, behavior, or docs]
 - Out of scope: [explicit exclusions]
 
-## Task Budget
-
-| Budget | Use When | Required Structure |
-| --- | --- | --- |
-| simple | One owner, no subagent, L0/L1 evidence, no formal review gate | `brief.md`, `task_plan.md`, `visual_map.md`, `progress.md` |
-| standard | Normal feature, fix, or documentation change | `brief.md`, `task_plan.md`, `execution_strategy.md`, `visual_map.md`, `findings.md`, `lesson_candidates.md`, `progress.md`, `review.md` |
-| complex | Multi-hour work, L2/L3 evidence, subagent/reviewer, or optional artifact/reference indexes | Standard files plus `references/INDEX.md` and `artifacts/INDEX.md` |
+## Selected Budget
 
 Selected budget: {{TASK_BUDGET}}
 
+Rationale: [why this budget fits this task]
+
 ## Context Packet
 
 | ID | Type | Path | Why It Matters | Used By |
 | --- | --- | --- | --- | --- |
 | C-001 | public-doc / private-plan / external / code | PUBLIC:path or PRIVATE:path or TARGET:path or URL:https://example.com | [why this source matters] | coordinator / reviewer / worker |
 
-## Required Files
-
-Do not hand-copy this template to create task directories. Use `harness new-task`
-so the selected budget creates the correct file set and `harness check` can
-enforce it.
-
-| Budget | Required Files |
-| --- | --- |
-| simple | `brief.md`, `task_plan.md`, `visual_map.md`, `progress.md` |
-| standard | simple files plus `execution_strategy.md`, `findings.md`, `lesson_candidates.md`, `review.md` |
-| complex | standard files plus `references/INDEX.md`, `artifacts/INDEX.md` |
-| long-running add-on | `long-running-task-contract.md` when `--long-running` is selected |
-
-Optional subdirectories are created only when triggered:
-
-- `lessons/LC-*.md`: task-local detail artifacts for lesson candidates marked `needs-promotion`.
-- `references/INDEX.md`: complex-task source package and reference index.
-- `artifacts/INDEX.md`: complex-task generated evidence and artifact index.
-
-File purposes:
-
-| Contract File | Purpose |
-| --- | --- |
-| `brief.md` | Human-readable task summary and current context packet |
-| `task_plan.md` | Goal, scope, budget, acceptance, and operating decisions |
-| `execution_strategy.md` | Operating model, allocation, conflict control, and evidence strategy |
-| `visual_map.md` | Diagram collection: phase map, optional architecture/sequence/data-flow/state diagrams, completion state, evidence state, and blocking risk |
-| `progress.md` | Execution log, decisions, and handoff |
-| `findings.md` | Findings, research notes, and unresolved risks |
-| `lesson_candidates.md` | Task-local lesson candidate queue. Human review must accept no-candidate, reject candidates, or queue promotion before review confirmation |
-| `lessons/LC-*.md` | Optional task-local lesson detail artifacts written while source context is fresh and linked from `Detail Artifact` |
-| `review.md` | Agent review submission, adversarial review, or specialist review report |
-| `references/INDEX.md` | Complex-task source package and reference index |
-| `artifacts/INDEX.md` | Complex-task generated evidence and artifact index |
-| `long-running-task-contract.md` | Continuous execution permission, loop rules, and stop conditions |
-
 ## Steps
 
 1. [First concrete step]

package/templates/planning/visual_map.md

@@ -15,22 +15,26 @@ Include only diagrams that materially help a human or agent understand the task.
 
 ```mermaid
 flowchart LR
-  PH01["PH-01 Plan"] --> PH02["PH-02 Implement"]
-  PH02 --> PH03["PH-03 Verify"]
-  PH03 --> PH04["PH-04 Review and Closeout"]
+  INIT01["INIT-01 Scope and Context\nkind=init"] --> EXEC01["EXEC-01 Implementation Slice\nkind=execution"]
+  EXEC01 --> GATE01["GATE-01 Agent Review Submission\nkind=gate"]
+  GATE01 --> GATE02["GATE-02 Human Review Confirmation\nkind=gate"]
 ```
 
 ## Phase Table
 
-| Phase ID | Depends On | State | Completion | Output | Required Evidence | Evidence Status | Blocking Risk | Owner / Handoff |
-| --- | --- | --- | ---: | --- | --- | --- | --- | --- |
-| PH-01 | none | planned | 0 | Approved task plan and execution strategy | `task_plan.md`, `execution_strategy.md` | missing | none | coordinator |
-| PH-02 | PH-01 | planned | 0 | Scoped implementation or document update | diff, worker handoff, or artifact path | missing | [risk] | [owner] |
-| PH-03 | PH-02 | planned | 0 | Verification evidence | commands, logs, screenshots, or runtime proof | missing | [risk] | [owner] |
-| PH-04 | PH-03 | planned | 0 | Review disposition and closeout updates | `review.md`, progress update, ledger updates | missing | [risk] | coordinator |
+| Phase ID | Kind | Depends On | State | Completion | Output | Required Evidence | Exit Command | Actor | Evidence Status | Blocking Risk | Owner / Handoff |
+| --- | --- | --- | --- | ---: | --- | --- | --- | --- | --- | --- | --- |
+| INIT-01 | init | none | planned | 0 | Approved task plan and execution strategy | `task_plan.md`, `execution_strategy.md` | `harness task-start {{TASK_ID}}` | agent | missing | none | coordinator |
+| EXEC-01 | execution | INIT-01 | planned | 0 | Scoped implementation, document update, and verification evidence | diff, commands, worker handoff, or artifact path | `harness task-phase {{TASK_ID}} EXEC-01 --state done --completion 100 --evidence present` | agent | missing | [risk] | [owner] |
+| GATE-01 | gate | EXEC-01 | planned | 0 | Agent Review Submission | `review.md`, progress update, lesson routing | `harness task-review {{TASK_ID}} --message "<summary>"` | agent | missing | [risk] | coordinator |
+| GATE-02 | gate | GATE-01 | planned | 0 | Human Review Confirmation | review packet and human confirmation | `harness review-confirm {{TASK_ID}} --confirm {{TASK_ID}}` | human | missing | agent must not perform human confirmation | human |
 
+Allowed Kind: init, execution, gate.
+Allowed Actor: agent, human, coordinator.
 Allowed Evidence Status: missing, partial, present, waived.
 
+Dashboard implementation completion is computed from non-skipped `execution` phases only. `init` and `gate` phases route lifecycle readiness and next actions; they must not make implementation progress look incomplete.
+
 ## Supporting Maps
 
 Add optional diagrams only when useful:

package/templates/planning/visual_map.simple.md

@@ -0,0 +1,52 @@
+# [Task Name] - Visual Map
+
+Visual Map Contract: v1.0
+
+This file is the task's diagram collection. It is not only a phase roadmap.
+Include only diagrams that materially help a human or agent understand the task.
+
+## Map Index
+
+| ID | Type | Purpose | Required For Understanding | Source Evidence | Promotion Candidate |
+| --- | --- | --- | --- | --- | --- |
+| MAP-01 | phase | Show the execution phases and dependencies | yes | `task_plan.md` | no |
+
+## Phase Graph
+
+```mermaid
+flowchart LR
+  INIT01["INIT-01 Scope and Context\nkind=init"] --> EXEC01["EXEC-01 Implementation Slice\nkind=execution"]
+  EXEC01 --> GATE01["GATE-01 Direct Completion\nkind=gate"]
+```
+
+## Phase Table
+
+| Phase ID | Kind | Depends On | State | Completion | Output | Required Evidence | Exit Command | Actor | Evidence Status | Blocking Risk | Owner / Handoff |
+| --- | --- | --- | --- | ---: | --- | --- | --- | --- | --- | --- | --- |
+| INIT-01 | init | none | planned | 0 | Task scope is clear enough to execute | `task_plan.md` | `harness task-start {{TASK_ID}}` | agent | missing | none | coordinator |
+| EXEC-01 | execution | INIT-01 | planned | 0 | Simple implementation or documentation change is complete | diff, command, or artifact path | `harness task-phase {{TASK_ID}} EXEC-01 --state done --completion 100 --evidence present` | agent | missing | [risk] | [owner] |
+| GATE-01 | gate | EXEC-01 | planned | 0 | Direct task completion | progress update and final evidence note | `harness task-complete {{TASK_ID}} --message "<summary>"` | agent | missing | [risk] | coordinator |
+
+Allowed Kind: init, execution, gate.
+Allowed Actor: agent, human, coordinator.
+Allowed Evidence Status: missing, partial, present, waived.
+
+Dashboard implementation completion is computed from non-skipped `execution` phases only. `init` and `gate` phases route lifecycle readiness and next actions; they must not make implementation progress look incomplete.
+
+## Supporting Maps
+
+Add optional diagrams only when useful:
+
+- architecture: module, component, or service structure.
+- sequence: frontend/backend/service/database/agent interaction.
+- data-flow: data movement and ownership.
+- state: state machine or lifecycle.
+- topology: repo, service, worker, or worktree layout.
+- decision: branch and tradeoff tree.
+
+## Map Notes
+
+- Use `missing` when no evidence has been checked.
+- Use `partial` when some evidence exists but required checks remain.
+- Use `present` when the phase has sufficient evidence for its current claim.
+- Use `waived` only when the reason and owner are recorded in `progress.md`.

package/templates/reference/execution-workflow-standard.md

@@ -13,16 +13,43 @@ Define the standard lifecycle for non-trivial work from intake through planning,
 5. Run checks that match the risk surface before claiming completion.
 6. Route material findings through review and do not bury unresolved issues in summaries.
 7. Proactively commit each verified, meaningful slice. A completed slice should not remain only as unstaged or staged working-tree state unless the user explicitly asked to defer commits, checks failed, dirty ownership is unclear, or a documented blocker prevents a clean commit. Deferred commits require a no-commit reason, owner, and next step.
-8. Use CLI lifecycle commands for mechanical Harness writes whenever available. CLI-owned writes use locked, allowlisted auto-commit and refuse dirty Git state; agent-owned manual edits still need an explicit task commit or deferred-commit rationale.
-9. Close the loop by updating walkthrough, SSoT, regression, ledger, or docs artifacts when the work changes durable project knowledge. New non-simple tasks should keep `lesson_candidates.md` reviewable before human review confirmation.
+8. Use CLI lifecycle commands for mechanical Harness writes whenever available. CLI-owned writes use locked, allowlisted auto-commit. `new-task` may preserve unrelated dirty files while committing only its own write scope; overlapping dirty paths or unrelated staged files still block the command. Other lifecycle commands may still require a clean tree. Agent-owned manual edits still need an explicit task commit or deferred-commit rationale.
+9. Treat `visual_map.md` as the lifecycle phase map. `init` phases prepare work, `execution` phases define implementation completion, and `gate` phases define review, human confirmation, lesson routing, and closeout. Follow a phase `Exit Command` only when its `Actor` matches the current operator; agents must not perform `human` gates.
+10. New task directories must carry machine-readable Task Audit Metadata in `INDEX.md`. The normal path is `Created By: harness new-task`; manual creation is allowed only as `manual-exception` with a concrete reason, and historical migration must use `historical-backfill`.
+11. Close the loop by updating walkthrough, SSoT, regression, ledger, or docs artifacts when the work changes durable project knowledge. New non-simple tasks should keep `lesson_candidates.md` reviewable before human review confirmation.
+
+## Task Package Structure
+
+Use `harness new-task` instead of hand-copying task files. The CLI creates the selected budget file set and records task audit metadata in `INDEX.md` so `harness check` can validate it.
+
+| Budget | Required Files |
+| --- | --- |
+| simple | `INDEX.md`, `brief.md`, `task_plan.md`, `visual_map.md`, `progress.md` |
+| standard | simple files plus `execution_strategy.md`, `findings.md`, `lesson_candidates.md`, `review.md` |
+| complex | standard files plus `references/INDEX.md`, `artifacts/INDEX.md` |
+| long-running add-on | `long-running-task-contract.md` when `--long-running` is selected |
+
+`INDEX.md` is the task package navigation page and audit metadata SSoT. It points to contract files and optional indexes but does not replace them.
+
+Optional directories are created only when triggered:
+
+- `references/INDEX.md`: task-local sources, external links, reviewer input packages, and preset-provided required reads.
+- `artifacts/INDEX.md`: command output, screenshots, fixtures, generated reports, reviews, and other evidence.
+- `lessons/LC-*.md`: task-local lesson detail artifacts for candidates marked `needs-promotion`.
+- `slices/<slice-id>/`: multi-slice task material, when a task explicitly uses slice packets.
+
+Preset packages must not add or replace root-level base scaffold documents. Presets may append controlled sections to fixed base documents or add isolated resources under `references/**` and `artifacts/**`. Resource rows belong only in `references/INDEX.md` and `artifacts/INDEX.md`; the root `INDEX.md` may show only system-rendered preset summary fields.
 
 ## Required Checklist
 
 - Goal, scope, acceptance criteria, and constraints are written down.
+- Task Audit Metadata is present in `INDEX.md`, or the manual/historical exception reason is explicit.
+- The task package `INDEX.md` is present for new generated tasks.
 - Current repo state and ownership boundaries were checked.
 - Implementation notes identify changed surfaces.
 - Required checks and evidence are captured.
 - Verified slices have commit SHAs, or the no-commit reason, owner, and next step are written down.
+- The current lifecycle gate in `visual_map.md` has either been executed or has a recorded blocker.
 - Review status and material findings are recorded.
 - Residuals are explicit and assigned.
 - Closeout artifacts are updated when required.

package/templates-zh-CN/AGENTS.md.template

@@ -15,10 +15,11 @@
 
 1. 遵守 `docs/11-REFERENCE/engineering-standard.md` 中的架构边界。
 2. 不提交密钥、令牌、私有接口、用户隐私数据或生产凭据。
-3. 非平凡任务先在 `docs/09-PLANNING/TASKS/` 下建立任务目录。
+3. 非平凡任务先用 Harness CLI 在 `docs/09-PLANNING/TASKS/` 下建立任务目录。
 4. 声称完成前必须记录证据。
 5. 保护无关工作区改动，不回滚任务范围外文件。
 6. 已验证的、有意义的工作切片要主动提交。除非用户明确暂停提交、检查失败、dirty 归属不清，或安全边界导致无法形成干净提交，否则不要把已完成工作只留在未提交文件里；不能提交时，必须在 progress、handoff 或 closeout 中写明 no-commit reason、owner 和下一步。不要把无关 dirty 改动混入本任务提交。
+7. 最终回复前检查当前任务 `visual_map.md` 的 gate 阶段。如果当前 `Exit Command` 的 `Actor` 是 `agent`，就执行它或记录 blocker。不得执行 `review-confirm` 这类 `human` gate，除非用户已经明确完成或委托了人工确认。
 
 ## 任务阅读矩阵
 
@@ -32,7 +33,7 @@
 | API、event、webhook、SDK、第三方契约 | `docs/06-INTEGRATIONS/README.md` 和相关契约文件 |
 | 测试、冒烟、回归 | `docs/11-REFERENCE/testing-standard.md`、`docs/05-TEST-QA/Regression-SSoT.md` |
 | 开发执行、提交、PR、发布 | `docs/11-REFERENCE/execution-workflow-standard.md`、`docs/11-REFERENCE/repo-governance-standard.md`、`docs/11-REFERENCE/pull-request-standard.md`、`docs/11-REFERENCE/ci-cd-standard.md` |
-| 创建或推进任务 | `docs/09-PLANNING/TASKS/` 下的当前任务目录；如果本项目已配置 Harness CLI，优先用 CLI |
+| 创建或推进任务 | `docs/09-PLANNING/TASKS/` 下的当前任务目录；如果本项目已配置 Harness CLI，使用 `harness new-task` / lifecycle 命令 |
 | Brief、Execution Strategy、Visual Map | 当前任务的 `brief.md`、`execution_strategy.md`、`visual_map.md` |
 | 长程任务 | `docs/11-REFERENCE/long-running-task-standard.md` |
 | reviewer、subagent、对抗性审查 | `docs/11-REFERENCE/review-routing-standard.md`、`docs/11-REFERENCE/adversarial-review-standard.md` |
@@ -47,7 +48,7 @@
 ## 标准执行流程
 
 1. 先确认请求、范围和受影响文件。
-2. 非平凡任务先创建或更新任务计划，再改代码。
+2. 非平凡任务先创建或更新任务计划，再改代码。优先使用 `harness new-task`；CLI 不可用时必须在任务 `INDEX.md` 保留任务审计元数据，并把 `Created By` 设为 `manual-exception`，写清具体原因。
 3. 根据用户目标主动判断是否需要分工；用户不需要知道或主动要求 subagent。
 4. 只读取任务阅读矩阵要求的 reference 文档。
 5. 保留已有项目事实；新增上下文使用 merge / append，不覆盖历史。
@@ -55,8 +56,9 @@
 7. 只在确认范围内实现。
 8. 运行相关检查，并把证据写入任务记录。
 9. 按需触发 review，关闭阻塞发现。
-10. 写入或更新 walkthrough 与 closeout 记录。
-11. 只更新本任务实际触达的 SSoT / ledger；任务生命周期总账优先由 Harness CLI 生成，不手写任务行。
+10. 按当前 `visual_map.md` lifecycle gate 的 `Exit Command` / `Actor` 收口。
+11. 写入或更新 walkthrough 与 closeout 记录。
+12. 只更新本任务实际触达的 SSoT / ledger；任务生命周期总账优先由 Harness CLI 生成，不手写任务行。
 
 ## 协作规则