coding-agent-harness 1.0.1 → 1.0.4

package/skills/preset-creator/references/complex-task-skeleton/progress.md

@@ -0,0 +1,33 @@
+# [Task Name] - Progress
+
+## Current Status
+
+planned
+
+## Log
+
+| Time | Actor | Action | Evidence | Next |
+| --- | --- | --- | --- | --- |
+| YYYY-MM-DD HH:MM | coordinator | [action taken] | type:path:summary | [next step] |
+
+## Decisions
+
+| Date | Decision | Reason | Owner |
+| --- | --- | --- | --- |
+| YYYY-MM-DD | [decision] | [reason] | [owner] |
+
+## Evidence Ledger
+
+| Evidence ID | Type | Path or Command | Result | Used For |
+| --- | --- | --- | --- | --- |
+| E-001 | command / file / runtime / review | [path or command] | pass / fail / observed / waived | [claim supported] |
+
+## Residual
+
+none
+
+## Coordinator Handoff
+
+- Global sync status: pending-coordinator-pass / synced / n/a
+- Owner: coordinator / n/a
+- Required shared updates: [none]

package/skills/preset-creator/references/complex-task-skeleton/references/INDEX.md

@@ -0,0 +1,13 @@
+# References Index
+
+Use this index for sources the task depends on but does not own.
+
+| ID | Type | Path | Summary | Used By |
+| --- | --- | --- | --- | --- |
+| [reference-id] | doc / link / transcript / code | TARGET:path or URL:https://example.com | [why this source is relevant] | coordinator |
+
+## Source Rules
+
+- Prefer canonical project files over summaries.
+- Record external links with enough context for a reviewer to re-check them.
+- Mark stale or uncertain references in `findings.md`.

package/skills/preset-creator/references/complex-task-skeleton/review.md

@@ -0,0 +1,107 @@
+# [Task Name] - Review
+
+## Reviewer Identity
+
+| Reviewer | Type | Scope |
+| --- | --- | --- |
+| [name] | self / subagent / external / human | [files, modules, behavior, or release surface] |
+
+## Review Scope
+
+- Review type: adversarial / security / regression / architecture / release / other
+- In scope: [files, modules, behavior]
+- Out of scope: [explicit exclusions]
+- Source materials: [task plan, diff, test output, runtime evidence]
+
+## Agent Review Submission
+
+This section is written by the agent or coordinator when the review packet is ready.
+It is not human approval.
+
+| Field | Value |
+| --- | --- |
+| Submission ID | [generated by task-review] |
+| Submitted At | [timestamp] |
+| Submitted By | [agent or coordinator identity] |
+| Task Key | {{TASK_ID}} |
+| Materials Checklist Hash | [generated by task-review; informational, not a manual gate] |
+| Evidence Summary | [tests, diff, runtime, and review packet evidence] |
+| Open Findings Count | [number] |
+| Scanner Version | [generated scanner version] |
+
+### Material Checklist
+
+| Material | Required? | Status | Evidence |
+| --- | --- | --- | --- |
+| Brief | yes / no | present / missing / incomplete | [path or reason] |
+| Task plan | yes / no | present / missing / incomplete | [path or reason] |
+| Progress and evidence | yes / no | present / missing / incomplete | [path or reason] |
+| Visual map | yes / no | present / missing / incomplete | [path or reason] |
+| Lesson candidate decision | yes / no | present / missing / incomplete | [path or reason] |
+| Walkthrough or closeout link | yes / no | present / missing / incomplete | [path or reason] |
+
+The scanner derives `materialsReady` from required files, sections, evidence, and this strict submission block. If materials are not ready, route the task to Missing Materials instead of Human Review Confirmation.
+If there are open P0/P1/P2 blocking findings, route the task to Blocked instead of Human Review Confirmation.
+
+## Confidence Challenge
+
+Answer directly: do you have 100% confidence in the plan, implementation, and strategy?
+
+- Verdict: yes / no
+- If no, list every plausible gap below and propose fixes.
+
+## Material Findings
+
+| ID | Severity | Finding | Evidence Checked | Required Action | Open | Disposition | Blocks Release | Follow-up |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+
+Do not keep sample findings. If there are no material findings, leave only the header and complete the No-Finding Statement.
+
+## No-Finding Statement
+
+[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 |
+| --- | --- | --- | --- |
+| E-001 | command / file / runtime | [path or command] | [what was checked and what it showed] |
+
+## Residual Risk
+
+| Risk | Owner | Accepted? | Follow-up |
+| --- | --- | --- | --- |
+| [risk] | [owner] | yes / no | [path or next action] |
+
+## Lifecycle Queue Routing
+
+| Queue | Applies? | Reason | Exit condition |
+| --- | --- | --- | --- |
+| Review | yes / no | Submitted review packet is ready for human confirmation. | Human confirms or returns it. |
+| Missing Materials | yes / no | Required file, section, evidence, or review submission is absent/incomplete. | Agent repairs materials and resubmits review. |
+| Blocked | yes / no | Open blocking finding, invalid state transition, failed audit, or human waiver needed. | Blocker is fixed, closed, or explicitly waived. |
+| Lessons | yes / no | Lesson candidate needs rejection, task-local retention, dry-run promotion, or a sedimentation task. | Human decides candidate routing; promotion remains a separate maintenance task unless explicitly approved. |
+| Confirmed / Finalized | yes / no | Human confirmation exists; closeout or governance work may still be pending. | Closeout, ledger, and lesson routing are complete. |
+| Soft-deleted / Superseded | yes / no | Task has tombstone, superseded-by, archive, duplicate, or abandoned status. | Reopen or keep as read-only audit history. |
+
+## Final Confidence Basis
+
+[Explain the final confidence basis after fixes and verification. If confidence is limited, name the remaining limits and who owns them.]

package/skills/preset-creator/references/complex-task-skeleton/task_plan.md

@@ -0,0 +1,111 @@
+# [Task Name]
+
+Task Contract: harness-task/v1
+
+## Goal
+
+[State the outcome this task must deliver in one sentence.]
+
+## Scope
+
+- 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: {{TASK_BUDGET}}
+
+## 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]
+2. [Second concrete step]
+3. [Third concrete step]
+
+## Acceptance Criteria
+
+- [ ] [Observable criterion]
+- [ ] [Verification criterion]
+- [ ] [Documentation or handoff criterion]
+
+## Worktree
+
+- Path: [worktree path or n/a]
+- Branch: [branch or n/a]
+- Worker owner: coordinator / subagent id / n/a
+- Worker handoff commit required: yes / no / n/a
+- If no worktree, reason: [reason]
+
+## Long-Running Task Decision
+
+- Long-running task: yes / no
+- Contract file if yes: `long-running-task-contract.md`
+- Continuous execution permission: granted / not granted / n/a
+- Stop condition summary: [one sentence]
+
+## Review Decision
+
+- Adversarial review required: yes / no
+- Report file if yes: `review.md`
+- Reviewer: self / subagent / external / human / n/a
+- No-finding requirement: [requirement or n/a]
+
+## Links
+
+- Related Regression Gate: [reference]
+- Review Report: [path / n/a]
+- Generated Ledger: rebuilt by lifecycle CLI / `harness governance rebuild`
+- Prerequisite tasks: [reference or none]
+
+## Coordinator Handoff
+
+- Global sync owner: coordinator / n/a
+- Global sync status: pending-coordinator-pass / synced / n/a
+- Shared updates needed: [Module Registry / Harness Ledger / Closeout SSoT / Regression SSoT / none]

package/{templates/planning/visual_roadmap.md → skills/preset-creator/references/complex-task-skeleton/visual_map.md}

@@ -1,4 +1,15 @@
-# [Task Name] - Visual Roadmap
+# [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
 
@@ -20,7 +31,18 @@ flowchart LR
 
 Allowed Evidence Status: missing, partial, present, waived.
 
-## Roadmap Notes
+## 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.

package/skills/preset-creator/references/preset-package-skeleton.md

@@ -0,0 +1,296 @@
+# Preset Package Skeleton
+
+Use this reference when creating a Coding Agent Harness preset package. Start from the smallest useful subset, then delete files and manifest sections the preset does not need.
+
+Before designing a complex-task preset, inspect `references/complex-task-skeleton/`. That folder shows the base task contract the preset overlays. Presets should add method-specific context and resources; they should not silently replace the complex task skeleton itself.
+
+## Copyable Package Tree
+
+```text
+my-preset/
+  preset.yaml
+  templates/
+    task_plan.append.md
+    references/
+      upstream-contract.md
+  resources/
+    service-runbook.md
+    artifacts/
+      input-packet.md
+```
+
+## Complete Reference Bundle Manifest
+
+```yaml
+id: service-context
+version: 1
+purpose: Create tasks with shared upstream service context
+compatibleBudgets: [complex]
+localeSupport: [en-US]
+task:
+  kind: service-integration
+  defaultTaskId: service-integration-task
+entrypoints:
+  newTask:
+    type: template
+    writes: [docs/09-PLANNING/TASKS/**]
+    audit: true
+    templates:
+      taskPlanAppend: templates/task_plan.append.md
+inputs:
+  service:
+    type: text
+    flag: --service
+    required: true
+templateValues:
+  service:
+    from: inputs.service
+metadata:
+  UpstreamService:
+    label: Upstream Service
+    from: inputs.service
+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
+  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
+context:
+  requiredReads: [REF-001, REF-002]
+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
+```
+
+## Starter Files
+
+### `templates/task_plan.append.md`
+
+```markdown
+## Preset Context
+
+This task depends on {{service}}. Read the preset required references before implementation and cite any behavior that changes the integration contract.
+```
+
+### `templates/references/upstream-contract.md`
+
+```markdown
+# {{service}} Contract
+
+## Purpose
+
+Record the contract details that every task created by this preset must understand before implementation.
+
+## Required Context
+
+- Service owner:
+- Local path or repository:
+- API, event, or data boundary:
+- Compatibility constraints:
+- Known test or smoke command:
+
+## Open Questions
+
+- [question]
+```
+
+### `resources/service-runbook.md`
+
+```markdown
+# Service Runbook
+
+## Local Setup
+
+- Command:
+- Required environment:
+- Health check:
+
+## Verification Notes
+
+- Integration smoke:
+- Known failure mode:
+```
+
+### `resources/artifacts/input-packet.md`
+
+```markdown
+# Input Packet
+
+## Fixture Purpose
+
+Describe why this shared input packet exists and which tasks should use it.
+
+## Contents
+
+- [fixture or packet item]
+```
+
+## Minimal Non-Resource Preset
+
+Use this smaller manifest when the preset only needs metadata, task-plan guidance, and audit evidence.
+
+```yaml
+id: custom-review
+version: 1
+purpose: Create a custom review task
+compatibleBudgets: [standard, complex]
+localeSupport: [en-US]
+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
+audit:
+  manifestRequired: true
+  evidenceFiles: [preset-audit.json, preset-manifest.json, write-scope.json]
+writeScopes:
+  taskDocs:
+    path: docs/09-PLANNING/TASKS/**
+    access: write
+```
+
+## File And Field Rules
+
+- `id` uses lowercase letters, numbers, and hyphens only.
+- Supported `inputs.*.type` values are `text`, `flag`, and `json-file`.
+- `entrypoints.newTask.writes` entries must exactly match declared `writeScopes.*.path` entries.
+- `path` for references must stay under `references/`.
+- `path` for artifacts must stay under `artifacts/`.
+- Do not target `references/INDEX.md`, `artifacts/INDEX.md`, `task_plan.md`, or any canonical task contract file.
+- `source` and `template` must point to files inside the preset package, not directories.
+- Resource `index.id` values must be unique inside references or artifacts.
+- Resource destination paths must be unique across references and artifacts.
+- `context.requiredReads` can only list declared reference IDs.
+- `context.requiredReads` generates `## Preset Required Reads` in `task_plan.md`; each generated row must contain the reference ID and the exact `TARGET:<task-relative-reference-path>`.
+- `evidence.bundleDir` names the task-local audit/evidence directory; `evidence.files` is an optional mapping of named custom evidence declarations, while `audit.evidenceFiles` names built-in audit files.
+- Do not write `evidence.files` as an array. Each custom evidence file must be a mapping with `path`, `type`, and `value`.
+- Supported custom evidence types are `text`, `json`, `input-json`, `preset-audit`, `preset-manifest`, `write-scope`, `migration-verify`, `migration-ledger`, `dashboard-hash`, `target-git-status`, `target-commit`, `harness-version`, and `generated-at`.
+- Resource `index.type`, `usedBy`, and `producedBy` are reader-facing labels, not strict enums. Prefer stable simple words: `code`, `doc`, `runbook`, `fixture`, `preset`, `coordinator`, `worker`, `reviewer`.
+- Keep `entrypoints.newTask.type` as `template`; do not add JavaScript for task creation.
+- Keep `writeScopes` narrow and task-doc scoped.
+
+## Custom Evidence Shape
+
+Use a mapping, not an array:
+
+```yaml
+evidence:
+  bundleDir: artifacts/preset
+  files:
+    subject:
+      path: subject.txt
+      type: text
+      value: inputs.subject
+    resolvedInputs:
+      path: resolved-inputs.json
+      type: json
+      value: inputs
+audit:
+  manifestRequired: true
+  evidenceFiles: [preset-audit.json, preset-manifest.json, write-scope.json]
+```
+
+This creates named files under the generated task's preset evidence bundle. Arrays such as `evidence.files: [summary.json]` are invalid.
+
+## Generated Required Reads Shape
+
+For a declared reference like:
+
+```yaml
+resources:
+  references:
+    upstreamContract:
+      path: references/upstream-contract.md
+      index:
+        id: REF-001
+context:
+  requiredReads: [REF-001]
+```
+
+The generated `task_plan.md` must include:
+
+```markdown
+## Preset Required Reads
+
+Open `references/INDEX.md`, then read these preset-provided references before implementation.
+
+| Reference | Path | Why |
+| --- | --- | --- |
+| REF-001 | TARGET:docs/09-PLANNING/TASKS/<task-folder>/references/upstream-contract.md | [rendered summary] |
+```
+
+The same `REF-001` and exact `TARGET:` path must also appear in `references/INDEX.md`.
+
+## Verification Checklist
+
+Run these commands in an isolated HOME or disposable target:
+
+```bash
+harness preset check ./my-preset
+harness preset install ./my-preset --force
+harness init --locale en-US --capabilities core /tmp/preset-target
+harness new-task first-api --budget complex --preset service-context --service payment-service /tmp/preset-target
+harness new-task second-api --budget complex --preset service-context --service payment-service /tmp/preset-target
+harness status --json /tmp/preset-target
+harness task-index --json /tmp/preset-target
+harness check --profile target-project /tmp/preset-target
+```
+
+Manually inspect both created tasks:
+
+- `task_plan.md` includes preset metadata and `## Preset Required Reads`.
+- `references/INDEX.md` includes every `REF-*` row with a concrete `TARGET:` path.
+- `artifacts/INDEX.md` includes every `ART-*` row with a concrete `TARGET:` path.
+- The copied or rendered reference files exist under each task directory.
+- Evidence bundles are independent per task.