coding-agent-harness 1.0.2 → 1.0.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (177) hide show
  1. package/CHANGELOG.md +25 -0
  2. package/CONTRIBUTING.md +98 -0
  3. package/README.md +211 -86
  4. package/README.zh-CN.md +54 -34
  5. package/SKILL.md +25 -18
  6. package/docs-release/README.md +9 -5
  7. package/docs-release/architecture/overview.md +17 -5
  8. package/docs-release/architecture/overview.zh-CN.md +9 -5
  9. package/docs-release/assets/dashboard-overview.png +0 -0
  10. package/docs-release/guides/agent-installation.en-US.md +31 -8
  11. package/docs-release/guides/agent-installation.md +34 -9
  12. package/docs-release/guides/contributing.md +100 -0
  13. package/docs-release/guides/contributing.zh-CN.md +99 -0
  14. package/docs-release/guides/document-audience-and-surfaces.en-US.md +3 -2
  15. package/docs-release/guides/document-audience-and-surfaces.md +3 -2
  16. package/docs-release/guides/full-legacy-migration-subagent-strategy.md +2 -2
  17. package/docs-release/guides/full-legacy-migration-subagent-strategy.zh-CN.md +2 -2
  18. package/docs-release/guides/legacy-migration-agent-prompt.md +0 -11
  19. package/docs-release/guides/legacy-migration-agent-prompt.zh-CN.md +0 -11
  20. package/docs-release/guides/migration-playbook.en-US.md +14 -15
  21. package/docs-release/guides/migration-playbook.md +14 -15
  22. package/docs-release/guides/parent-control-repository-pattern.en-US.md +7 -5
  23. package/docs-release/guides/parent-control-repository-pattern.md +7 -5
  24. package/docs-release/guides/preset-development.md +214 -0
  25. package/docs-release/guides/repository-operating-models.en-US.md +5 -4
  26. package/docs-release/guides/repository-operating-models.md +5 -4
  27. package/docs-release/guides/task-state-machine.en-US.md +207 -0
  28. package/docs-release/guides/task-state-machine.md +214 -0
  29. package/docs-release/intl/en-US.md +1 -1
  30. package/docs-release/intl/zh-CN.md +1 -1
  31. package/examples/minimal-project/docs/09-PLANNING/TASKS/demo-task/findings.md +7 -0
  32. package/package.json +8 -3
  33. package/presets/legacy-migration/checks/preset-check.mjs +3 -0
  34. package/presets/legacy-migration/preset.yaml +134 -0
  35. package/presets/legacy-migration/scripts/plan-work-queue.mjs +4 -0
  36. package/presets/legacy-migration/scripts/scaffold-task-contracts.mjs +4 -0
  37. package/presets/legacy-migration/templates/execution_strategy.append.md +18 -0
  38. package/presets/legacy-migration/templates/findings.seed.md +17 -0
  39. package/presets/legacy-migration/templates/review.seed.md +12 -0
  40. package/presets/legacy-migration/templates/task_plan.append.md +9 -0
  41. package/presets/legacy-migration/templates/visual_map.append.md +12 -0
  42. package/presets/legacy-migration/workbench/dashboard-panels.yaml +2 -0
  43. package/presets/legacy-migration/workbench/migration-queue.schema.json +23 -0
  44. package/presets/lesson-sedimentation/preset.yaml +23 -0
  45. package/presets/lesson-sedimentation/templates/prompt.md +23 -0
  46. package/presets/module/preset.yaml +25 -0
  47. package/presets/module/templates/execution_strategy.append.md +8 -0
  48. package/presets/module/templates/task_plan.append.md +17 -0
  49. package/presets/standard-task/preset.yaml +31 -0
  50. package/presets/standard-task/templates/task_plan.append.md +7 -0
  51. package/references/adversarial-review-standard.md +2 -2
  52. package/references/agents-md-pattern.md +2 -2
  53. package/references/delivery-operating-model-standard.md +3 -3
  54. package/references/docs-directory-standard.md +6 -7
  55. package/references/harness-ledger.md +53 -96
  56. package/references/lessons-governance.md +88 -93
  57. package/references/module-parallel-standard.md +14 -14
  58. package/references/planning-loop.md +12 -6
  59. package/references/pull-request-standard.md +118 -0
  60. package/references/repo-governance-standard.md +11 -2
  61. package/references/review-routing-standard.md +7 -1
  62. package/references/ssot-governance.md +67 -59
  63. package/references/taskr-gap-analysis.md +600 -0
  64. package/references/walkthrough-closeout.md +7 -7
  65. package/scripts/check-harness.mjs +40 -301
  66. package/scripts/commands/dashboard-command.mjs +67 -0
  67. package/scripts/commands/migration-command.mjs +96 -0
  68. package/scripts/commands/preset-command.mjs +73 -0
  69. package/scripts/commands/task-command.mjs +327 -0
  70. package/scripts/harness.mjs +55 -260
  71. package/scripts/lib/capability-registry.mjs +66 -8
  72. package/scripts/lib/check-module-parallel.mjs +237 -0
  73. package/scripts/lib/check-profiles.mjs +61 -153
  74. package/scripts/lib/check-task-contracts.mjs +47 -0
  75. package/scripts/lib/core-shared.mjs +10 -0
  76. package/scripts/lib/dashboard-data.mjs +29 -6
  77. package/scripts/lib/dashboard-workbench.mjs +52 -12
  78. package/scripts/lib/dashboard-writer.mjs +14 -2
  79. package/scripts/lib/git-status-summary.mjs +46 -0
  80. package/scripts/lib/governance-index-generator.mjs +174 -0
  81. package/scripts/lib/governance-sync.mjs +514 -0
  82. package/scripts/lib/governance-table-boundary.mjs +175 -0
  83. package/scripts/lib/harness-core.mjs +5 -0
  84. package/scripts/lib/lesson-maintenance.mjs +36 -29
  85. package/scripts/lib/migration-support.mjs +1 -1
  86. package/scripts/lib/preset-audit-contracts.mjs +37 -0
  87. package/scripts/lib/preset-engine.mjs +497 -0
  88. package/scripts/lib/preset-registry.mjs +627 -0
  89. package/scripts/lib/preset-resource-contracts.mjs +83 -0
  90. package/scripts/lib/review-confirm-git-gate.mjs +248 -0
  91. package/scripts/lib/status-dashboard-renderer.mjs +102 -0
  92. package/scripts/lib/subagent-authorization-audit.mjs +196 -0
  93. package/scripts/lib/task-completion-consistency.mjs +16 -0
  94. package/scripts/lib/task-index.mjs +93 -0
  95. package/scripts/lib/task-lesson-candidates.mjs +242 -0
  96. package/scripts/lib/task-lesson-sedimentation.mjs +326 -0
  97. package/scripts/lib/task-lifecycle/review-confirm.mjs +101 -0
  98. package/scripts/lib/task-lifecycle/review-gates.mjs +70 -0
  99. package/scripts/lib/task-lifecycle/text-utils.mjs +24 -0
  100. package/scripts/lib/task-lifecycle.mjs +297 -403
  101. package/scripts/lib/task-review-model.mjs +469 -0
  102. package/scripts/lib/task-scanner.mjs +130 -236
  103. package/scripts/lib/task-tombstone-commands.mjs +140 -0
  104. package/scripts/postinstall.mjs +14 -0
  105. package/skills/preset-creator/SKILL.md +179 -0
  106. package/skills/preset-creator/references/complex-task-skeleton/README.md +31 -0
  107. package/skills/preset-creator/references/complex-task-skeleton/artifacts/INDEX.md +12 -0
  108. package/skills/preset-creator/references/complex-task-skeleton/brief.md +32 -0
  109. package/skills/preset-creator/references/complex-task-skeleton/execution_strategy.md +71 -0
  110. package/skills/preset-creator/references/complex-task-skeleton/findings.md +24 -0
  111. package/skills/preset-creator/references/complex-task-skeleton/lesson_candidates.md +70 -0
  112. package/skills/preset-creator/references/complex-task-skeleton/long-running-task-contract.md +76 -0
  113. package/skills/preset-creator/references/complex-task-skeleton/progress.md +33 -0
  114. package/skills/preset-creator/references/complex-task-skeleton/references/INDEX.md +13 -0
  115. package/skills/preset-creator/references/complex-task-skeleton/review.md +107 -0
  116. package/skills/preset-creator/references/complex-task-skeleton/task_plan.md +111 -0
  117. package/skills/preset-creator/references/complex-task-skeleton/visual_map.md +50 -0
  118. package/skills/preset-creator/references/preset-package-skeleton.md +296 -0
  119. package/templates/AGENTS.md.template +19 -15
  120. package/templates/dashboard/assets/app-src/00-state.js +1 -0
  121. package/templates/dashboard/assets/app-src/10-router.js +2 -1
  122. package/templates/dashboard/assets/app-src/20-overview.js +11 -5
  123. package/templates/dashboard/assets/app-src/30-tasks.js +92 -246
  124. package/templates/dashboard/assets/app-src/35-task-detail.js +246 -0
  125. package/templates/dashboard/assets/app-src/45-review.js +241 -22
  126. package/templates/dashboard/assets/app-src/50-migration.js +24 -10
  127. package/templates/dashboard/assets/app-src/90-bindings.js +171 -29
  128. package/templates/dashboard/assets/app.css +698 -156
  129. package/templates/dashboard/assets/app.css.manifest.json +9 -0
  130. package/templates/dashboard/assets/app.js +662 -91
  131. package/templates/dashboard/assets/app.manifest.json +1 -0
  132. package/templates/dashboard/assets/css-src/00-foundation.css +342 -0
  133. package/templates/dashboard/assets/css-src/10-panels-flow.css +236 -0
  134. package/templates/dashboard/assets/css-src/20-briefs-controls.css +398 -0
  135. package/templates/dashboard/assets/css-src/30-task-index.css +739 -0
  136. package/templates/dashboard/assets/css-src/35-review-workspace.css +507 -0
  137. package/templates/dashboard/assets/css-src/40-detail-modules-migration.css +427 -0
  138. package/templates/dashboard/assets/css-src/50-responsive-overrides.css +551 -0
  139. package/templates/dashboard/assets/i18n.js +123 -21
  140. package/templates/ledger/Harness-Ledger.md +13 -25
  141. package/templates/lessons/lesson-arch-process-change.md +1 -1
  142. package/templates/lessons/lesson-new-doc.md +1 -1
  143. package/templates/lessons/lesson-ref-change.md +1 -1
  144. package/templates/planning/execution_strategy.md +31 -0
  145. package/templates/planning/lesson_candidates.md +18 -6
  146. package/templates/planning/optional/artifacts/INDEX.md +3 -3
  147. package/templates/planning/optional/references/INDEX.md +3 -3
  148. package/templates/planning/review.md +59 -0
  149. package/templates/planning/task_plan.md +36 -13
  150. package/templates/reference/execution-workflow-standard.md +4 -3
  151. package/templates/reference/pull-request-standard.md +80 -0
  152. package/templates/reference/repo-governance-standard.md +7 -6
  153. package/templates/reference/review-routing-standard.md +6 -0
  154. package/templates/reference/walkthrough-standard.md +2 -1
  155. package/templates/verifier/verifier-output.md +1 -1
  156. package/templates-zh-CN/AGENTS.md.template +20 -16
  157. package/templates-zh-CN/ledger/Harness-Ledger.md +17 -40
  158. package/templates-zh-CN/planning/execution_strategy.md +30 -0
  159. package/templates-zh-CN/planning/lesson_candidates.md +18 -6
  160. package/templates-zh-CN/planning/review.md +59 -1
  161. package/templates-zh-CN/planning/task_plan.md +30 -10
  162. package/templates-zh-CN/reference/adversarial-review-standard.md +1 -1
  163. package/templates-zh-CN/reference/docs-library-standard.md +1 -1
  164. package/templates-zh-CN/reference/execution-workflow-standard.md +4 -3
  165. package/templates-zh-CN/reference/harness-ledger-standard.md +2 -2
  166. package/templates-zh-CN/reference/pull-request-standard.md +106 -0
  167. package/templates-zh-CN/reference/repo-governance-standard.md +4 -3
  168. package/templates-zh-CN/reference/review-routing-standard.md +8 -1
  169. package/templates-zh-CN/reference/walkthrough-standard.md +3 -2
  170. package/templates-zh-CN/walkthrough/Closeout-SSoT.md +1 -1
  171. package/docs-release/assets/dashboard-overview-en.png +0 -0
  172. package/scripts/smoke-dashboard.mjs +0 -92
  173. package/scripts/test-harness.mjs +0 -1395
  174. package/templates/ssot/Feature-SSoT.md +0 -43
  175. package/templates/ssot/Lessons-SSoT.md +0 -44
  176. package/templates-zh-CN/ssot/Feature-SSoT.md +0 -49
  177. package/templates-zh-CN/ssot/Lessons-SSoT.md +0 -49
@@ -0,0 +1,111 @@
1
+ # [Task Name]
2
+
3
+ Task Contract: harness-task/v1
4
+
5
+ ## Goal
6
+
7
+ [State the outcome this task must deliver in one sentence.]
8
+
9
+ ## Scope
10
+
11
+ - In scope: [specific files, modules, behavior, or docs]
12
+ - Out of scope: [explicit exclusions]
13
+
14
+ ## Task Budget
15
+
16
+ | Budget | Use When | Required Structure |
17
+ | --- | --- | --- |
18
+ | simple | One owner, no subagent, L0/L1 evidence, no formal review gate | `brief.md`, `task_plan.md`, `visual_map.md`, `progress.md` |
19
+ | 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` |
20
+ | complex | Multi-hour work, L2/L3 evidence, subagent/reviewer, or optional artifact/reference indexes | Standard files plus `references/INDEX.md` and `artifacts/INDEX.md` |
21
+
22
+ Selected budget: {{TASK_BUDGET}}
23
+
24
+ ## Context Packet
25
+
26
+ | ID | Type | Path | Why It Matters | Used By |
27
+ | --- | --- | --- | --- | --- |
28
+ | 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 |
29
+
30
+ ## Required Files
31
+
32
+ Do not hand-copy this template to create task directories. Use `harness new-task`
33
+ so the selected budget creates the correct file set and `harness check` can
34
+ enforce it.
35
+
36
+ | Budget | Required Files |
37
+ | --- | --- |
38
+ | simple | `brief.md`, `task_plan.md`, `visual_map.md`, `progress.md` |
39
+ | standard | simple files plus `execution_strategy.md`, `findings.md`, `lesson_candidates.md`, `review.md` |
40
+ | complex | standard files plus `references/INDEX.md`, `artifacts/INDEX.md` |
41
+ | long-running add-on | `long-running-task-contract.md` when `--long-running` is selected |
42
+
43
+ Optional subdirectories are created only when triggered:
44
+
45
+ - `lessons/LC-*.md`: task-local detail artifacts for lesson candidates marked `needs-promotion`.
46
+ - `references/INDEX.md`: complex-task source package and reference index.
47
+ - `artifacts/INDEX.md`: complex-task generated evidence and artifact index.
48
+
49
+ File purposes:
50
+
51
+ | Contract File | Purpose |
52
+ | --- | --- |
53
+ | `brief.md` | Human-readable task summary and current context packet |
54
+ | `task_plan.md` | Goal, scope, budget, acceptance, and operating decisions |
55
+ | `execution_strategy.md` | Operating model, allocation, conflict control, and evidence strategy |
56
+ | `visual_map.md` | Diagram collection: phase map, optional architecture/sequence/data-flow/state diagrams, completion state, evidence state, and blocking risk |
57
+ | `progress.md` | Execution log, decisions, and handoff |
58
+ | `findings.md` | Findings, research notes, and unresolved risks |
59
+ | `lesson_candidates.md` | Task-local lesson candidate queue. Human review must accept no-candidate, reject candidates, or queue promotion before review confirmation |
60
+ | `lessons/LC-*.md` | Optional task-local lesson detail artifacts written while source context is fresh and linked from `Detail Artifact` |
61
+ | `review.md` | Agent review submission, adversarial review, or specialist review report |
62
+ | `references/INDEX.md` | Complex-task source package and reference index |
63
+ | `artifacts/INDEX.md` | Complex-task generated evidence and artifact index |
64
+ | `long-running-task-contract.md` | Continuous execution permission, loop rules, and stop conditions |
65
+
66
+ ## Steps
67
+
68
+ 1. [First concrete step]
69
+ 2. [Second concrete step]
70
+ 3. [Third concrete step]
71
+
72
+ ## Acceptance Criteria
73
+
74
+ - [ ] [Observable criterion]
75
+ - [ ] [Verification criterion]
76
+ - [ ] [Documentation or handoff criterion]
77
+
78
+ ## Worktree
79
+
80
+ - Path: [worktree path or n/a]
81
+ - Branch: [branch or n/a]
82
+ - Worker owner: coordinator / subagent id / n/a
83
+ - Worker handoff commit required: yes / no / n/a
84
+ - If no worktree, reason: [reason]
85
+
86
+ ## Long-Running Task Decision
87
+
88
+ - Long-running task: yes / no
89
+ - Contract file if yes: `long-running-task-contract.md`
90
+ - Continuous execution permission: granted / not granted / n/a
91
+ - Stop condition summary: [one sentence]
92
+
93
+ ## Review Decision
94
+
95
+ - Adversarial review required: yes / no
96
+ - Report file if yes: `review.md`
97
+ - Reviewer: self / subagent / external / human / n/a
98
+ - No-finding requirement: [requirement or n/a]
99
+
100
+ ## Links
101
+
102
+ - Related Regression Gate: [reference]
103
+ - Review Report: [path / n/a]
104
+ - Generated Ledger: rebuilt by lifecycle CLI / `harness governance rebuild`
105
+ - Prerequisite tasks: [reference or none]
106
+
107
+ ## Coordinator Handoff
108
+
109
+ - Global sync owner: coordinator / n/a
110
+ - Global sync status: pending-coordinator-pass / synced / n/a
111
+ - Shared updates needed: [Module Registry / Harness Ledger / Closeout SSoT / Regression SSoT / none]
@@ -0,0 +1,50 @@
1
+ # [Task Name] - Visual Map
2
+
3
+ Visual Map Contract: v1.0
4
+
5
+ This file is the task's diagram collection. It is not only a phase roadmap.
6
+ Include only diagrams that materially help a human or agent understand the task.
7
+
8
+ ## Map Index
9
+
10
+ | ID | Type | Purpose | Required For Understanding | Source Evidence | Promotion Candidate |
11
+ | --- | --- | --- | --- | --- | --- |
12
+ | MAP-01 | phase | Show the execution phases and dependencies | yes | `task_plan.md` | no |
13
+
14
+ ## Phase Graph
15
+
16
+ ```mermaid
17
+ flowchart LR
18
+ PH01["PH-01 Plan"] --> PH02["PH-02 Implement"]
19
+ PH02 --> PH03["PH-03 Verify"]
20
+ PH03 --> PH04["PH-04 Review and Closeout"]
21
+ ```
22
+
23
+ ## Phase Table
24
+
25
+ | Phase ID | Depends On | State | Completion | Output | Required Evidence | Evidence Status | Blocking Risk | Owner / Handoff |
26
+ | --- | --- | --- | ---: | --- | --- | --- | --- | --- |
27
+ | PH-01 | none | planned | 0 | Approved task plan and execution strategy | `task_plan.md`, `execution_strategy.md` | missing | none | coordinator |
28
+ | PH-02 | PH-01 | planned | 0 | Scoped implementation or document update | diff, worker handoff, or artifact path | missing | [risk] | [owner] |
29
+ | PH-03 | PH-02 | planned | 0 | Verification evidence | commands, logs, screenshots, or runtime proof | missing | [risk] | [owner] |
30
+ | PH-04 | PH-03 | planned | 0 | Review disposition and closeout updates | `review.md`, progress update, ledger updates | missing | [risk] | coordinator |
31
+
32
+ Allowed Evidence Status: missing, partial, present, waived.
33
+
34
+ ## Supporting Maps
35
+
36
+ Add optional diagrams only when useful:
37
+
38
+ - architecture: module, component, or service structure.
39
+ - sequence: frontend/backend/service/database/agent interaction.
40
+ - data-flow: data movement and ownership.
41
+ - state: state machine or lifecycle.
42
+ - topology: repo, service, worker, or worktree layout.
43
+ - decision: branch and tradeoff tree.
44
+
45
+ ## Map Notes
46
+
47
+ - Use `missing` when no evidence has been checked.
48
+ - Use `partial` when some evidence exists but required checks remain.
49
+ - Use `present` when the phase has sufficient evidence for its current claim.
50
+ - Use `waived` only when the reason and owner are recorded in `progress.md`.
@@ -0,0 +1,296 @@
1
+ # Preset Package Skeleton
2
+
3
+ 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.
4
+
5
+ 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.
6
+
7
+ ## Copyable Package Tree
8
+
9
+ ```text
10
+ my-preset/
11
+ preset.yaml
12
+ templates/
13
+ task_plan.append.md
14
+ references/
15
+ upstream-contract.md
16
+ resources/
17
+ service-runbook.md
18
+ artifacts/
19
+ input-packet.md
20
+ ```
21
+
22
+ ## Complete Reference Bundle Manifest
23
+
24
+ ```yaml
25
+ id: service-context
26
+ version: 1
27
+ purpose: Create tasks with shared upstream service context
28
+ compatibleBudgets: [complex]
29
+ localeSupport: [en-US]
30
+ task:
31
+ kind: service-integration
32
+ defaultTaskId: service-integration-task
33
+ entrypoints:
34
+ newTask:
35
+ type: template
36
+ writes: [docs/09-PLANNING/TASKS/**]
37
+ audit: true
38
+ templates:
39
+ taskPlanAppend: templates/task_plan.append.md
40
+ inputs:
41
+ service:
42
+ type: text
43
+ flag: --service
44
+ required: true
45
+ templateValues:
46
+ service:
47
+ from: inputs.service
48
+ metadata:
49
+ UpstreamService:
50
+ label: Upstream Service
51
+ from: inputs.service
52
+ resources:
53
+ references:
54
+ upstreamContract:
55
+ path: references/upstream-contract.md
56
+ template: templates/references/upstream-contract.md
57
+ index:
58
+ id: REF-001
59
+ type: code
60
+ summary: Shared upstream {{service}} contract for every task created by this preset.
61
+ usedBy: coordinator,worker,reviewer
62
+ serviceRunbook:
63
+ path: references/service-runbook.md
64
+ source: resources/service-runbook.md
65
+ index:
66
+ id: REF-002
67
+ type: runbook
68
+ summary: Local verification notes for the shared upstream service.
69
+ usedBy: worker
70
+ artifacts:
71
+ inputPacket:
72
+ path: artifacts/input-packet.md
73
+ source: resources/artifacts/input-packet.md
74
+ index:
75
+ id: ART-001
76
+ type: fixture
77
+ summary: Shared fixture packet copied by the preset.
78
+ producedBy: preset
79
+ context:
80
+ requiredReads: [REF-001, REF-002]
81
+ evidence:
82
+ bundleDir: artifacts/preset
83
+ files:
84
+ subject:
85
+ path: subject.txt
86
+ type: text
87
+ value: inputs.subject
88
+ audit:
89
+ manifestRequired: true
90
+ evidenceFiles: [preset-audit.json, preset-manifest.json, write-scope.json]
91
+ writeScopes:
92
+ taskDocs:
93
+ path: docs/09-PLANNING/TASKS/**
94
+ access: write
95
+ ```
96
+
97
+ ## Starter Files
98
+
99
+ ### `templates/task_plan.append.md`
100
+
101
+ ```markdown
102
+ ## Preset Context
103
+
104
+ This task depends on {{service}}. Read the preset required references before implementation and cite any behavior that changes the integration contract.
105
+ ```
106
+
107
+ ### `templates/references/upstream-contract.md`
108
+
109
+ ```markdown
110
+ # {{service}} Contract
111
+
112
+ ## Purpose
113
+
114
+ Record the contract details that every task created by this preset must understand before implementation.
115
+
116
+ ## Required Context
117
+
118
+ - Service owner:
119
+ - Local path or repository:
120
+ - API, event, or data boundary:
121
+ - Compatibility constraints:
122
+ - Known test or smoke command:
123
+
124
+ ## Open Questions
125
+
126
+ - [question]
127
+ ```
128
+
129
+ ### `resources/service-runbook.md`
130
+
131
+ ```markdown
132
+ # Service Runbook
133
+
134
+ ## Local Setup
135
+
136
+ - Command:
137
+ - Required environment:
138
+ - Health check:
139
+
140
+ ## Verification Notes
141
+
142
+ - Integration smoke:
143
+ - Known failure mode:
144
+ ```
145
+
146
+ ### `resources/artifacts/input-packet.md`
147
+
148
+ ```markdown
149
+ # Input Packet
150
+
151
+ ## Fixture Purpose
152
+
153
+ Describe why this shared input packet exists and which tasks should use it.
154
+
155
+ ## Contents
156
+
157
+ - [fixture or packet item]
158
+ ```
159
+
160
+ ## Minimal Non-Resource Preset
161
+
162
+ Use this smaller manifest when the preset only needs metadata, task-plan guidance, and audit evidence.
163
+
164
+ ```yaml
165
+ id: custom-review
166
+ version: 1
167
+ purpose: Create a custom review task
168
+ compatibleBudgets: [standard, complex]
169
+ localeSupport: [en-US]
170
+ task:
171
+ kind: review-task
172
+ defaultTaskId: custom-review-task
173
+ entrypoints:
174
+ newTask:
175
+ type: template
176
+ writes: [docs/09-PLANNING/TASKS/**]
177
+ audit: true
178
+ templates:
179
+ taskPlanAppend: templates/task_plan.append.md
180
+ inputs:
181
+ subject:
182
+ type: text
183
+ flag: --subject
184
+ required: true
185
+ templateValues:
186
+ subject:
187
+ from: inputs.subject
188
+ metadata:
189
+ ReviewSubject:
190
+ label: Review Subject
191
+ from: inputs.subject
192
+ evidence:
193
+ bundleDir: artifacts/preset
194
+ audit:
195
+ manifestRequired: true
196
+ evidenceFiles: [preset-audit.json, preset-manifest.json, write-scope.json]
197
+ writeScopes:
198
+ taskDocs:
199
+ path: docs/09-PLANNING/TASKS/**
200
+ access: write
201
+ ```
202
+
203
+ ## File And Field Rules
204
+
205
+ - `id` uses lowercase letters, numbers, and hyphens only.
206
+ - Supported `inputs.*.type` values are `text`, `flag`, and `json-file`.
207
+ - `entrypoints.newTask.writes` entries must exactly match declared `writeScopes.*.path` entries.
208
+ - `path` for references must stay under `references/`.
209
+ - `path` for artifacts must stay under `artifacts/`.
210
+ - Do not target `references/INDEX.md`, `artifacts/INDEX.md`, `task_plan.md`, or any canonical task contract file.
211
+ - `source` and `template` must point to files inside the preset package, not directories.
212
+ - Resource `index.id` values must be unique inside references or artifacts.
213
+ - Resource destination paths must be unique across references and artifacts.
214
+ - `context.requiredReads` can only list declared reference IDs.
215
+ - `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>`.
216
+ - `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.
217
+ - Do not write `evidence.files` as an array. Each custom evidence file must be a mapping with `path`, `type`, and `value`.
218
+ - 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`.
219
+ - 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`.
220
+ - Keep `entrypoints.newTask.type` as `template`; do not add JavaScript for task creation.
221
+ - Keep `writeScopes` narrow and task-doc scoped.
222
+
223
+ ## Custom Evidence Shape
224
+
225
+ Use a mapping, not an array:
226
+
227
+ ```yaml
228
+ evidence:
229
+ bundleDir: artifacts/preset
230
+ files:
231
+ subject:
232
+ path: subject.txt
233
+ type: text
234
+ value: inputs.subject
235
+ resolvedInputs:
236
+ path: resolved-inputs.json
237
+ type: json
238
+ value: inputs
239
+ audit:
240
+ manifestRequired: true
241
+ evidenceFiles: [preset-audit.json, preset-manifest.json, write-scope.json]
242
+ ```
243
+
244
+ This creates named files under the generated task's preset evidence bundle. Arrays such as `evidence.files: [summary.json]` are invalid.
245
+
246
+ ## Generated Required Reads Shape
247
+
248
+ For a declared reference like:
249
+
250
+ ```yaml
251
+ resources:
252
+ references:
253
+ upstreamContract:
254
+ path: references/upstream-contract.md
255
+ index:
256
+ id: REF-001
257
+ context:
258
+ requiredReads: [REF-001]
259
+ ```
260
+
261
+ The generated `task_plan.md` must include:
262
+
263
+ ```markdown
264
+ ## Preset Required Reads
265
+
266
+ Open `references/INDEX.md`, then read these preset-provided references before implementation.
267
+
268
+ | Reference | Path | Why |
269
+ | --- | --- | --- |
270
+ | REF-001 | TARGET:docs/09-PLANNING/TASKS/<task-folder>/references/upstream-contract.md | [rendered summary] |
271
+ ```
272
+
273
+ The same `REF-001` and exact `TARGET:` path must also appear in `references/INDEX.md`.
274
+
275
+ ## Verification Checklist
276
+
277
+ Run these commands in an isolated HOME or disposable target:
278
+
279
+ ```bash
280
+ harness preset check ./my-preset
281
+ harness preset install ./my-preset --force
282
+ harness init --locale en-US --capabilities core /tmp/preset-target
283
+ harness new-task first-api --budget complex --preset service-context --service payment-service /tmp/preset-target
284
+ harness new-task second-api --budget complex --preset service-context --service payment-service /tmp/preset-target
285
+ harness status --json /tmp/preset-target
286
+ harness task-index --json /tmp/preset-target
287
+ harness check --profile target-project /tmp/preset-target
288
+ ```
289
+
290
+ Manually inspect both created tasks:
291
+
292
+ - `task_plan.md` includes preset metadata and `## Preset Required Reads`.
293
+ - `references/INDEX.md` includes every `REF-*` row with a concrete `TARGET:` path.
294
+ - `artifacts/INDEX.md` includes every `ART-*` row with a concrete `TARGET:` path.
295
+ - The copied or rendered reference files exist under each task directory.
296
+ - Evidence bundles are independent per task.
@@ -19,7 +19,7 @@ Keep it as a charter and routing index. Detailed rules belong in
19
19
  3. Start non-trivial work with a task directory under `docs/09-PLANNING/TASKS/`.
20
20
  4. Record evidence before claiming completion.
21
21
  5. Protect unrelated working-tree changes; never revert files outside the assigned scope.
22
- 6. Commit verified, meaningful work slices unless the user explicitly says not to commit.
22
+ 6. Commit verified, meaningful work slices proactively. Do not leave completed work only as dirty files unless the user explicitly pauses commits, checks fail, dirty ownership is unclear, or a security boundary prevents a clean commit; in those cases record the no-commit reason, owner, and next step in progress, handoff, or closeout notes. Never mix unrelated dirty changes into a task commit.
23
23
 
24
24
  ## Reading Matrix
25
25
 
@@ -32,7 +32,7 @@ Read the smallest context that can answer the task.
32
32
  | Local development, mocks, stubs, or cross-repo debugging | `docs/04-DEVELOPMENT/README.md`, `docs/04-DEVELOPMENT/codebase-map.md` |
33
33
  | API, event, webhook, SDK, or third-party contract | `docs/06-INTEGRATIONS/README.md` and the related contract file |
34
34
  | Tests, smoke, or regression | `docs/11-REFERENCE/testing-standard.md`, `docs/05-TEST-QA/Regression-SSoT.md` |
35
- | Execution, commit, PR, or release work | `docs/11-REFERENCE/execution-workflow-standard.md`, `docs/11-REFERENCE/repo-governance-standard.md`, `docs/11-REFERENCE/ci-cd-standard.md` |
35
+ | Execution, commit, PR, or release work | `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` |
36
36
  | Creating or advancing a task | Current task directory under `docs/09-PLANNING/TASKS/`; use the Harness CLI if this project has it configured |
37
37
  | Brief, Execution Strategy, or Visual Map | Current task `brief.md`, `execution_strategy.md`, and `visual_map.md` |
38
38
  | Long-running task | `docs/11-REFERENCE/long-running-task-standard.md` |
@@ -42,37 +42,41 @@ Read the smallest context that can answer the task.
42
42
  | Documentation governance or Harness update | `docs/11-REFERENCE/docs-library-standard.md`, `.harness-capabilities.json` |
43
43
  | External source material intake | `docs/11-REFERENCE/external-source-intake-standard.md` |
44
44
  | Regression SSoT maintenance | `docs/11-REFERENCE/regression-ssot-governance.md` |
45
- | Walkthrough, closeout, or lessons | `docs/11-REFERENCE/walkthrough-standard.md`, `docs/10-WALKTHROUGH/Closeout-SSoT.md`, `docs/01-GOVERNANCE/Lessons-SSoT.md` |
45
+ | Walkthrough, closeout, or lessons | `docs/11-REFERENCE/walkthrough-standard.md`, `docs/10-WALKTHROUGH/Closeout-SSoT.md`, current task `lesson_candidates.md`, `docs/01-GOVERNANCE/lessons/` |
46
46
  | Worktree operations | `docs/11-REFERENCE/worktree-standard.md` |
47
47
 
48
48
  ## Standard Execution Flow
49
49
 
50
50
  1. Confirm the request, scope, and affected files.
51
51
  2. For non-trivial work, create or update the task plan before editing code.
52
- 3. Load only the reference documents required by the Reading Matrix.
53
- 4. Preserve existing project facts; merge new context instead of overwriting history.
54
- 5. Use a worktree or branch when the task requires isolation or parallel work.
55
- 6. Implement only within the approved scope.
56
- 7. Run the relevant checks and capture evidence in the task records.
57
- 8. Route required review and close blocking findings.
58
- 9. Write or update the walkthrough and closeout records.
59
- 10. Update SSoT / ledger files that the task actually touched.
52
+ 3. Assess delegation from the user's goal; users do not need to know or ask for subagents.
53
+ 4. Load only the reference documents required by the Reading Matrix.
54
+ 5. Preserve existing project facts; merge new context instead of overwriting history.
55
+ 6. Use a worktree or branch when the task requires isolation or parallel work.
56
+ 7. Implement only within the approved scope.
57
+ 8. Run the relevant checks and capture evidence in the task records.
58
+ 9. Route required review and close blocking findings.
59
+ 10. Write or update the walkthrough and closeout records.
60
+ 11. Update SSoT / ledger files that the task actually touched.
60
61
 
61
62
  ## Coordination Rules
62
63
 
63
- - Reviewers are read-only unless explicitly assigned a write scope.
64
- - Workers may edit only their assigned branch, worktree, and file scope.
64
+ - At task start, read the current task `execution_strategy.md` Subagent Authorization and Subagent Delegation Decision sections, then state whether reviewer or worker subagents should be used; do this even when the user only states the desired outcome.
65
+ - Reviewer subagents are allowed by default for read-only review within the current task.
66
+ - If a worker subagent would materially help and is not authorized, proactively ask the user once in plain language for task/scope/worktree authorization; it is fine to say "worker subagent", but do not wait for the user to know or suggest subagents.
67
+ - If independent slices are obvious but exact file paths are not, identify the file paths first and then immediately ask for independent-execution-helper authorization before implementation.
68
+ - Worker subagents require one user authorization recorded in `execution_strategy.md`; after that, reuse is allowed only within the same task, scope, and worktree/branch.
65
69
  - Shared ledgers, registries, and SSoT files are coordinator-owned unless a lock is explicitly assigned.
66
70
  - Worker handoff must include branch or worktree, changed files, checks, evidence, and residual risks.
67
71
 
68
72
  ## Single Sources Of Truth
69
73
 
70
- - Feature SSoT: `docs/09-PLANNING/Feature-SSoT.md`
71
74
  - Delivery SSoT: `docs/09-PLANNING/Delivery-SSoT.md`
72
75
  - Module Registry: `docs/09-PLANNING/Module-Registry.md`
73
76
  - Regression SSoT: `docs/05-TEST-QA/Regression-SSoT.md`
74
77
  - Cadence Ledger: `docs/05-TEST-QA/Cadence-Ledger.md`
75
- - Lessons SSoT: `docs/01-GOVERNANCE/Lessons-SSoT.md`
78
+ - Lesson Candidates: current task `lesson_candidates.md`
79
+ - Lesson Detail Docs: `docs/01-GOVERNANCE/lessons/`
76
80
  - Closeout SSoT: `docs/10-WALKTHROUGH/Closeout-SSoT.md`
77
81
  - Harness Ledger: `docs/Harness-Ledger.md`
78
82
 
@@ -15,6 +15,7 @@ const state = {
15
15
  renderMode: "rendered",
16
16
  theme: localStorage.getItem("harness.theme") || "system",
17
17
  taskLayout: localStorage.getItem("harness.taskLayout") || "list",
18
+ taskSortOrder: localStorage.getItem("harness.taskSortOrder") === "asc" ? "asc" : "desc",
18
19
  runtime: { mode: "static", csrfToken: "", writableActions: [] },
19
20
  runtimeLoaded: false,
20
21
  runtimePoller: null,
@@ -71,6 +71,7 @@ function currentRoute() {
71
71
  }
72
72
 
73
73
  function routeLink(hash, text, routeName) {
74
- const active = currentRoute().name === routeName;
74
+ const current = currentRoute().name;
75
+ const active = current === routeName || (routeName === "review" && current === "reviewTask");
75
76
  return `<a class="${active ? "active" : ""}" href="${hash}">${escapeHtml(text)}</a>`;
76
77
  }
@@ -165,24 +165,29 @@ function graphSummary() {
165
165
  }
166
166
 
167
167
  function activeTaskBriefs() {
168
- const tasks = activeTasks().slice(0, 8);
168
+ const tasks = activeTasks();
169
169
  return `<section class="task-briefs">
170
170
  <div class="section-head">
171
171
  <div>
172
172
  <p class="eyebrow">${t("currentWork")}</p>
173
173
  <h2>${t("activeBriefs")}</h2>
174
174
  </div>
175
- <a href="#/tasks">${t("openTaskIndex")}</a>
175
+ <div class="section-actions">
176
+ <span class="subtle">${t("activeBriefCount").replace("{count}", tasks.length).replace("{order}", taskSortLabel())}</span>
177
+ <a href="#/tasks">${t("openTaskIndex")}</a>
178
+ </div>
179
+ </div>
180
+ <div class="brief-scroll">
181
+ <div class="brief-grid">${tasks.map((task) => taskBriefCard(task, { compact: false })).join("") || emptyState(t("noActiveTasks"))}</div>
176
182
  </div>
177
- <div class="brief-grid">${tasks.map((task) => taskBriefCard(task, { compact: false })).join("") || emptyState(t("noActiveTasks"))}</div>
178
183
  </section>`;
179
184
  }
180
185
 
181
186
  function activeTasks() {
182
187
  const tasks = bundle.status?.tasks || [];
183
188
  const active = tasks.filter((task) => isActiveTaskState(task.state) || ["planned", "not_started"].includes(task.state));
184
- if (active.length > 0) return active;
185
- return tasks.filter((task) => task.briefSource === "standalone").slice(0, 6);
189
+ if (active.length > 0) return sortTasksByTime(active);
190
+ return sortTasksByTime(tasks.filter((task) => task.briefSource === "standalone"));
186
191
  }
187
192
 
188
193
  function isActiveTaskState(state) {
@@ -205,6 +210,7 @@ function taskBriefCard(task, { compact = true } = {}) {
205
210
  <p class="brief-teaser">${escapeHtml(summaryText)}</p>
206
211
  </div>
207
212
  <div class="card-actions">
213
+ ${taskCopyButton(task)}
208
214
  <button class="btn-drawer-trigger" data-open-drawer="${escapeAttr(task.id)}">${t("viewDetails")}</button>
209
215
  </div>
210
216
  </article>`;