coding-agent-harness 1.0.2 → 1.0.4

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

@@ -0,0 +1,214 @@
+# Preset Development
+
+Harness presets are declarative task method packages. A preset can add task metadata, render Markdown templates, require CLI inputs, generate evidence files, and pre-load shared reference bundles without writing JavaScript.
+
+Use a preset when multiple tasks should start from the same method, evidence contract, or shared context. Do not create a preset for one-off prose. Good presets encode repeatable task behavior: required inputs, task kind, review/evidence expectations, shared references, and a small amount of task-plan guidance that tells the next agent what to read first.
+
+`preset.yaml` uses the Harness manifest subset: nested mappings, scalar strings/numbers/booleans, and inline arrays such as `[standard, complex]`. Do not use block strings or dash-list YAML forms in preset manifests.
+
+## Install Location
+
+Project presets live in:
+
+```text
+<target>/.coding-agent-harness/presets/<preset-id>/
+```
+
+User-installed presets live in:
+
+```text
+~/.coding-agent-harness/presets/<preset-id>/
+```
+
+When a target is supplied, Harness discovers project presets first, then user presets, then bundled presets under the package `presets/` directory. Use project presets when a repository needs to override or pin a task method. Use user presets for personal reusable methods across repositories.
+
+Bundled presets are not only fallback files. `npm install -g coding-agent-harness`
+and `harness install-user` seed them into the user preset root, while
+`harness init` seeds them into the project preset root. Re-run
+`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.
+
+## Package Layout
+
+```text
+my-preset/
+  preset.yaml
+  templates/
+    task_plan.append.md
+    references/
+      upstream-contract.md
+  resources/
+    service-runbook.md
+```
+
+## Minimal Manifest
+
+```yaml
+id: custom-review
+version: 1
+purpose: Create a review task with preset evidence.
+compatibleBudgets: [standard, complex]
+localeSupport: [en-US, zh-CN]
+task:
+  kind: review-task
+  defaultTaskId: custom-review-task
+entrypoints:
+  newTask:
+    type: template
+    writes: [docs/09-PLANNING/TASKS/**]
+    audit: true
+    templates:
+      taskPlanAppend: templates/task_plan.append.md
+inputs:
+  subject:
+    type: text
+    flag: --subject
+    required: true
+templateValues:
+  subject:
+    from: inputs.subject
+metadata:
+  ReviewSubject:
+    label: Review Subject
+    from: inputs.subject
+evidence:
+  bundleDir: artifacts/preset
+  files:
+    subject:
+      path: subject.txt
+      type: text
+      value: inputs.subject
+audit:
+  manifestRequired: true
+  evidenceFiles: [preset-audit.json, preset-manifest.json, write-scope.json]
+writeScopes:
+  taskDocs:
+    path: docs/09-PLANNING/TASKS/**
+    access: write
+```
+
+## Reference Bundles
+
+Use `resources.references` when a family of tasks shares the same outside context, such as another microservice, API contract, migration packet, reviewer input, or local verification runbook. Harness copies or renders these files into each created task directory, appends `references/INDEX.md` rows, and can add a required-read section to `task_plan.md`.
+
+```yaml
+resources:
+  references:
+    upstreamContract:
+      path: references/upstream-contract.md
+      template: templates/references/upstream-contract.md
+      index:
+        id: REF-001
+        type: code
+        summary: Shared upstream {{service}} contract for every task created by this preset.
+        usedBy: coordinator,worker,reviewer
+    serviceRunbook:
+      path: references/service-runbook.md
+      source: resources/service-runbook.md
+      index:
+        id: REF-002
+        type: runbook
+        summary: Local verification notes for the shared upstream service.
+        usedBy: worker
+context:
+  requiredReads: [REF-001, REF-002]
+```
+
+Use `template` when the file needs `{{valueName}}` substitution. Use `source` when the file should be copied as static Markdown. `path`, `source`, and `template` must stay inside the preset package and generated task directory boundaries.
+
+## Artifact Bundles
+
+Use `resources.artifacts` for preset-provided fixtures, generated input packets, or review material that supports the task but is not a reference source of truth. Harness writes these files into the task's `artifacts/` area and appends `artifacts/INDEX.md`.
+
+```yaml
+resources:
+  artifacts:
+    inputPacket:
+      path: artifacts/input-packet.md
+      source: resources/artifacts/input-packet.md
+      index:
+        id: ART-001
+        type: fixture
+        summary: Shared fixture packet copied by the preset.
+        producedBy: preset
+```
+
+## Template Rendering
+
+Templates use `{{valueName}}` placeholders from `templateValues`. `templateValues` and `metadata` support literal `value`, `default`, and dot-path `from` references such as `inputs.subject` or `task.title`; they do not evaluate arbitrary expressions.
+
+`metadata` entries render first-class task plan lines such as `Review Subject: API contracts`.
+
+```md
+## Custom Review
+
+Subject: {{subject}}
+```
+
+## Inputs
+
+Supported input types:
+
+| Type | Use |
+| --- | --- |
+| `text` | Reads a CLI flag value such as `--subject "API"` |
+| `flag` | Reads a boolean CLI flag |
+| `json-file` | Reads and validates a JSON file such as `--from-session session.json` |
+
+`json-file` inputs can validate `validateOperation`, reject `planOnly`, require a target path, and route the task target from the JSON session.
+
+## Evidence
+
+Evidence files are written under the task directory and must match `writeScopes`.
+
+Supported evidence types:
+
+| Type | Output |
+| --- | --- |
+| `text` | Plain text from a value path |
+| `json` | JSON from a value path |
+| `input-json` | Raw resolved JSON input |
+| `preset-audit` | Manifest audit payload |
+| `preset-manifest` | Manifest snapshot |
+| `write-scope` | Declared write scopes |
+| `migration-verify` | Built-in migrate session verification |
+| `migration-ledger` | Built-in migration phase ledger |
+| `dashboard-hash` | Hash of the migration dashboard snapshot |
+| `target-git-status` | Target Git status from migration session |
+| `target-commit` | Current target commit |
+| `harness-version` | Current package version |
+| `generated-at` | Generation timestamp |
+
+## Commands
+
+```bash
+harness preset check ./my-preset
+harness preset install ./my-preset
+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 preset uninstall custom-review
+```
+
+## Validation Method
+
+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.
+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>`.
+6. Inspect `task_plan.md` to confirm required reads are visible before implementation starts.
+
+## Boundaries
+
+- Presets cannot write outside declared `writeScopes`.
+- Presets do not run arbitrary JavaScript during `new-task`.
+- Reference bundles are task-local snapshots. If the shared upstream context changes later, create a new preset version or a follow-up task rather than silently mutating historical tasks.
+- Script and check entrypoints may exist in bundled packages, but the task creation path is YAML + templates + built-in processors.
+- Use a new built-in processor only when multiple presets need the same capability and the behavior can be tested centrally.

package/docs-release/guides/repository-operating-models.en-US.md

@@ -92,7 +92,7 @@ Each repository should document its external boundary in:
 
 The risk is harness fragmentation:
 
-- The frontend Feature SSoT says a task is complete while the backend Regression SSoT is still red.
+- The frontend local task state says a task is complete while the backend Regression SSoT is still red.
 - An SDK breaking change is not projected into the product shell.
 - An agent starts from a child repository, sees only local facts, and incorrectly treats the global task as complete.
 
@@ -124,7 +124,8 @@ product-control-repo/
 The parent repository is the control plane. It owns:
 
 - Overall architecture and repo topology.
-- Cross-repo Feature SSoT.
+- Cross-repo task lifecycle Ledger.
+- Delivery SSoT when release or block orchestration is needed.
 - Task plans, reviews, and walkthroughs.
 - Regression SSoT and cross-repo cadence.
 - Agent entrypoint and reading matrix.
@@ -152,7 +153,7 @@ The parent-control model fixes global truth in one place. Even if there are 100
 
 This avoids:
 
-- Conflicting Feature SSoTs.
+- Conflicting handwritten task lifecycle tables.
 - Each child repo saying "done" while the release still cannot ship.
 - Agents starting from the wrong repository and seeing only local context.
 - Cross-repo review and regression evidence scattered across many places.
@@ -179,7 +180,7 @@ If cross-repo features remain common, create a parent-control repository.
 Migration order:
 
 1. Create the parent `AGENTS.md` and repo topology.
-2. Move global Feature SSoT, Regression SSoT, and walkthrough index into the parent repository.
+2. Move global Harness Ledger, Delivery SSoT, Regression SSoT, and walkthrough index into the parent repository.
 3. Keep local `AGENTS.md` files in child repositories, but point global planning back to the parent.
 4. Create new cross-repo tasks only in the parent repository.
 5. Treat child repository commits as evidence for parent tasks.

package/docs-release/guides/repository-operating-models.md

@@ -92,7 +92,7 @@ sdk-repo/
 
 多仓独立模式的风险是 Harness 分裂：
 
-- 前端 Feature SSoT 认为任务完成，后端 Regression SSoT 仍是红灯。
+- 前端局部任务状态认为任务完成，后端 Regression SSoT 仍是红灯。
 - SDK 的 breaking change 没有投影到产品 shell。
 - Agent 从子仓库启动后，只看到局部事实，误以为全局任务已经结束。
 
@@ -124,7 +124,8 @@ product-control-repo/
 父仓库是 control plane。它管理：
 
 - 总体架构和 repo topology。
-- 跨仓 Feature SSoT。
+- 跨仓任务生命周期 Ledger。
+- Delivery SSoT（需要 release / block 编排时）。
 - 任务计划、review、walkthrough。
 - Regression SSoT 和跨仓 cadence。
 - Agent 启动入口和读文件矩阵。
@@ -152,7 +153,7 @@ product-control-repo/
 
 这能避免：
 
-- 多个 Feature SSoT 互相冲突。
+- 多个手写任务生命周期表互相冲突。
 - 每个子仓库都声称自己已经完成，但 release 仍不能发。
 - Agent 从错误仓库启动，只看到局部上下文。
 - 跨仓 review 和 regression 证据散落在不同地方。
@@ -179,7 +180,7 @@ product-control-repo/
 迁移顺序：
 
 1. 创建父仓库 `AGENTS.md` 和 repo topology。
-2. 把全局 Feature SSoT、Regression SSoT、walkthrough index 收到父仓库。
+2. 把全局 Harness Ledger、Delivery SSoT、Regression SSoT、walkthrough index 收到父仓库。
 3. 子仓库保留局部 `AGENTS.md`，但把全局计划指向父仓库。
 4. 新跨仓任务只在父仓库创建 task。
 5. 子仓库提交只作为父任务的 evidence。

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

@@ -0,0 +1,207 @@
+# Task State Machine And Lifecycle Queues
+
+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.
+- `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.
+- The scanner derives `lifecycleState`, `reviewStatus`, `closeoutStatus`, `taskQueues[]`, `queueReasons[]`, and `repairPrompt` from those files.
+
+The older `reviewQueueState` model was enough for a single review page. After PF-024, the public model is a set of lifecycle queues: Review, Missing Materials, Blocked, Lessons, Confirmed / Finalized, and Soft-deleted / Superseded.
+
+## Raw Task Command Flow
+
+```mermaid
+stateDiagram-v2
+  [*] --> not_started: new-task
+  not_started --> in_progress: task-start
+  planned --> in_progress: task-start
+  in_progress --> in_progress: task-log / task-phase
+  in_progress --> blocked: task-block
+  blocked --> in_progress: blocker fixed
+  in_progress --> review_submitted: task-review
+  review_submitted --> missing_materials: returned for materials
+  missing_materials --> in_progress: repair materials
+  review_submitted --> blocked: blocking finding
+  review_submitted --> human_confirmed: review-confirm
+  human_confirmed --> finalized: task-complete + closeout
+  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.
+
+## Derived State
+
+```mermaid
+flowchart TB
+  Progress["progress.md<br/>task.state + evidence"]
+  Review["review.md<br/>Agent Review Submission + findings + Human Review Confirmation"]
+  Lessons["lesson_candidates.md<br/>decision + sedimentation route"]
+  Closeout["Closeout-SSoT.md<br/>closeout row + walkthrough"]
+  Tombstone["tombstone / supersede metadata"]
+  Scanner["scanner"]
+
+  Progress --> Scanner
+  Review --> Scanner
+  Lessons --> Scanner
+  Closeout --> Scanner
+  Tombstone --> Scanner
+
+  Scanner --> Lifecycle["lifecycleState"]
+  Scanner --> ReviewStatus["reviewStatus"]
+  Scanner --> CloseoutStatus["closeoutStatus"]
+  Scanner --> Queues["taskQueues[]"]
+  Scanner --> Reasons["queueReasons[]"]
+  Scanner --> Prompt["repairPrompt"]
+```
+
+| 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. |
+| `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. |
+| `queueReasons[]` | scanner-derived | Why the task entered a queue, including source file, field, and repair action. |
+| `repairPrompt` | scanner-derived | A copyable, scoped repair prompt for a Coding Agent. |
+
+## Lifecycle Matrix
+
+| Condition | `lifecycleState` | Meaning |
+| --- | --- | --- |
+| 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.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. |
+
+## Review Status
+
+| `reviewStatus` | Meaning |
+| --- | --- |
+| `missing` | No usable review document or Agent Review Submission exists. |
+| `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. |
+
+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`.
+
+## Lifecycle Queues
+
+The Dashboard lifecycle workbench is a set of queues, not one mixed review list.
+
+```mermaid
+flowchart TD
+  Task["task facts"]
+  Task --> Deleted{"tombstone / superseded / archived?"}
+  Deleted -->|yes| QDeleted["Soft-deleted / Superseded"]
+  Deleted -->|no| Blocker{"blocking finding or invalid transition?"}
+  Blocker -->|yes| QBlocked["Blocked"]
+  Blocker -->|no| Missing{"required materials missing?"}
+  Missing -->|yes| QMissing["Missing Materials"]
+  Missing -->|no| Submitted{"Agent Review Submission exists?"}
+  Submitted -->|yes + not human confirmed| QReview["Review"]
+  Submitted -->|no| Out["not in human review queue"]
+  Submitted -->|yes + human confirmed| Confirmed{"finalization complete?"}
+  Confirmed -->|no| QConfirmed["Confirmed / Finalized"]
+  Confirmed -->|yes| QFinal["Confirmed / Finalized"]
+  Task --> Lessons{"lesson candidate needs decision or sedimentation?"}
+  Lessons -->|yes| QLessons["Lessons"]
+```
+
+| Queue | Entry condition | Primary owner | Exit condition |
+| --- | --- | --- | --- |
+| Review | Review packet submitted, materials ready, and no human confirmation yet. | human | Human confirms or returns it. |
+| Missing Materials | Missing file, section, evidence, lesson decision, review submission, or incomplete phase. | agent | Agent repairs materials and resubmits review. |
+| Blocked | Blocking finding, state conflict, Git audit failure, completion gate failure, or human waiver required. | agent + human | Fixed, closed, or explicitly waived. |
+| Lessons | Lesson candidate needs decision, task-local retention, rejection, dry-run promotion, or a sedimentation task. | human + agent | Decision is complete, or a traceable sedimentation task exists. |
+| Confirmed / Finalized | Human-confirmed, or finalized and ready for read-only tracing. | coordinator | Closeout, ledger, and lesson routing are complete; then read-only. |
+| Soft-deleted / Superseded | Task was soft-deleted, replaced, merged, archived, or abandoned. | coordinator | Read-only tracing; reopen only when needed. |
+
+The Review queue only waits for human confirmation. Missing materials, blockers, lesson sedimentation, confirmed-but-not-finalized work, and historical superseded tasks must not masquerade as Review queue items.
+
+## Global Table Boundary
+
+Global governance tables only keep index, state, route, and audit summary. They help the Dashboard find the source of truth, but they do not carry module-local facts, long evidence, execution logs, or temporary repair prompts.
+
+| Layer | Should record | Should not record |
+| --- | --- | --- |
+| Global tables: Harness Ledger, Closeout SSoT, Regression SSoT, Cadence Ledger, Delivery SSoT | Current state, owner, task/module/detail links, regression gate, delivery sequence, closeout or audit summary | Module-internal steps, undecided lesson candidates, full command output, long evidence paragraphs, review transcripts, temporary repair prompts |
+| Module layer: Module Registry, `module_plan.md` | Module boundary, module steps, handoff, current blockers, and local evidence indexes | Final promoted lesson body or cross-module release audit ledger |
+| Task layer: `brief.md`, `task_plan.md`, `progress.md`, `review.md`, `lesson_candidates.md`, `lessons/LC-*.md`, `artifacts/INDEX.md` | Execution detail, evidence, agent review, candidate lessons, task-local lesson detail, repair prompts, and raw artifact routing | Cross-task ledgers or promoted lesson detail bodies |
+
+The checker enforces this boundary for new global table rows. Overloaded rows that already existed before 2026-05-24 are surfaced in Dashboard migration advice as `legacy-report-only`; they are not automatically deleted or bulk-rewritten. New rows that continue placing task/module-local detail in global tables are reported as `governance-table-entropy` failures. Lesson candidates stay in `lesson_candidates.md`; candidates that enter `needs-promotion` must link a task-local `lessons/LC-*.md` detail artifact, and accepted reusable lessons live in `docs/01-GOVERNANCE/lessons/*.md`. The fix is to keep the global summary row and move detail into module/task/detail documents linked from that row.
+
+## Human Confirmation Loop
+
+```mermaid
+sequenceDiagram
+  autonumber
+  participant Agent as Agent / coordinator
+  participant Human as Human reviewer
+  participant UI as Dashboard Workbench
+  participant API as workbench API
+  participant Lifecycle as task lifecycle writer
+  participant Docs as markdown files
+  participant Scanner as scanner
+
+  Agent->>Docs: write Agent Review Submission + evidence
+  Agent->>UI: submit task-review
+  Human->>UI: open Review queue item
+  UI->>API: POST /api/tasks/review-complete
+  API->>Scanner: read current task facts
+  Scanner-->>API: taskQueues, queueReasons, reviewStatus
+  alt not in Review queue
+    API-->>UI: reject with target queue
+  else missing material or blocker
+    API-->>UI: reject with repairPrompt
+  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: 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.
+
+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.
+
+## Lesson Sedimentation
+
+Lesson promotion does not write a shared Lessons table. The Dashboard or CLI should prefer a dry-run or follow-up sedimentation task so the assignee first:
+
+- Classifies scope and boundary reason.
+- Reads the task-local detail artifact referenced by the candidate row instead of reconstructing the lesson from the brief row.
+- Checks conflicts against existing lesson candidates, lesson detail docs, reference standards, templates, and checkers.
+- Proposes a target diff or no-action reason.
+- Writes the promoted lesson detail doc or standard update only after human approval.
+
+`needs-promotion` should not block human review confirmation by itself, but it must enter the Lessons queue and remain traceable in closeout / ledger records.
+
+## Soft Delete And Supersede
+
+The document library does not hard-delete task directories by default.
+
+| State | Meaning | Requirement |
+| --- | --- | --- |
+| `active` | Normal task. | Dashboard shows it by default. |
+| `soft-deleted` | Task was abandoned but the directory stays. | Write a tombstone with operator, timestamp, reason, and reopen eligibility. |
+| `superseded` | Task was replaced or merged into a newer task. | Old task records `Superseded By`; new task records `Supersedes`. |
+| `archived` | Task moved to archive. | Reference checks must pass first, and a redirect stub or generated index entry must remain. |
+| `hard-deleted` | Physically deleted. | Forbidden by default; allowed only for mistaken tasks with no references, ledger, progress, or review evidence. |
+
+The Soft-deleted / Superseded queue is read-only tracing. It tells users why a task is not active and which task replaced it.