coding-agent-harness 1.0.2 → 1.0.4

package/skills/preset-creator/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: preset-creator
+description: Use when creating, reviewing, improving, or installing Coding Agent Harness preset packages for repeatable task families.
+---
+
+# Preset Creator
+
+Use this skill when a user wants to create, review, improve, or install a Harness preset.
+
+A good preset is not just a folder template. It is a reusable task method package: it captures when a class of tasks should exist, what inputs the agent must ask for, what task metadata must be visible, what shared references must be read, what evidence must be produced, and how the created task proves it is using the preset correctly.
+
+This skill is standalone. Do not assume the agent already knows Harness task contracts. Before creating a preset for complex tasks, read the included complex task skeleton reference and design the preset as an overlay on that skeleton.
+
+## Preset Methodology
+
+Create a preset when at least two future tasks should share the same method or context. Good examples:
+
+- A group of API tasks all depend on the same upstream microservice contract.
+- Migration tasks all need the same baseline session evidence and cutover rules.
+- Review tasks all need the same reviewer input packet and required evidence.
+- Repeated lesson-sedimentation tasks need the same prompt, metadata, and audit trail.
+
+Do not create a preset for a one-off task. Do not use a preset to hide vague requirements. If the task family is not repeatable yet, write a normal task first and extract the preset after the second or third repetition.
+
+## Design Questions
+
+Before writing files, answer these in the task notes or your response:
+
+1. What family of tasks will this preset create?
+2. What task budget is required: `standard` or `complex`?
+3. What `task.kind` should downstream scanners see?
+4. What inputs must the user or agent provide as CLI flags?
+5. What metadata lines must appear in `task_plan.md`?
+6. What templates should be appended to task files?
+7. What evidence or audit files should be generated?
+8. What shared references should every preset-created task read first?
+9. What write scopes are strictly necessary?
+10. How will you prove a task created by this preset is recognized by `status --json` and `task-index --json`?
+
+## Package Layout
+
+Use the bundled references before writing files:
+
+- `references/complex-task-skeleton/`
+- `references/preset-package-skeleton.md`
+
+The complex task skeleton reference contains the base `brief.md`, `task_plan.md`, `execution_strategy.md`, `visual_map.md`, `findings.md`, `lesson_candidates.md`, `progress.md`, `review.md`, `references/INDEX.md`, and `artifacts/INDEX.md` contracts. The preset package skeleton contains a copyable package tree, a complete `preset.yaml`, starter Markdown resources, and the verification checklist. Keep this `SKILL.md` focused on method and judgment; use the references when the task has moved from design to file creation.
+
+Use a simple package:
+
+```text
+my-preset/
+  preset.yaml
+  templates/
+    task_plan.append.md
+    references/
+      upstream-contract.md
+  resources/
+    service-runbook.md
+    artifacts/
+      input-packet.md
+```
+
+## Required Manifest Sections
+
+- `id`: lowercase letters, numbers, and hyphens.
+- `version`: integer; increment when generated task behavior changes.
+- `purpose`: one sentence explaining the repeatable method.
+- `compatibleBudgets`: usually `[complex]` when the preset creates references or artifacts.
+- `task.kind`: stable scanner-facing task kind.
+- `entrypoints.newTask`: always declarative for task creation.
+- `inputs`: CLI flags when the preset needs user-provided values.
+- `templateValues`: values used by templates.
+- `metadata`: first-class `Label: value` lines in `task_plan.md`.
+- `resources.references`: shared task-local reference files, when tasks share context.
+- `resources.artifacts`: preset-provided fixtures or input packets, when needed.
+- `context.requiredReads`: reference IDs the agent must read before implementation.
+- `evidence.bundleDir`: task-local directory for preset audit/evidence files, usually `artifacts/preset`.
+- `evidence.files`: optional custom generated files inside the evidence bundle.
+- `audit.manifestRequired`: must be `true`.
+- `audit.evidenceFiles`: built-in audit files to generate, usually `preset-audit.json`, `preset-manifest.json`, and `write-scope.json`.
+- `writeScopes`: narrow paths the preset may write.
+
+## Manifest Format
+
+Use the Harness manifest subset only: nested mappings, scalar strings/numbers/booleans, and inline arrays such as `[standard, complex]`. Do not use block strings or dash-list YAML forms.
+
+`templateValues` and `metadata` may use literal `value`, `default`, or dot-path `from` references such as `inputs.subject` or `task.title`. Do not use expressions or inline code.
+
+Templates and resource index summaries can use `{{valueName}}` placeholders from `templateValues`.
+
+Supported input types are `text`, `flag`, and `json-file`. Resource `index.type`, `usedBy`, and `producedBy` are labels for readers; use stable simple words such as `code`, `runbook`, `doc`, `fixture`, `preset`, `worker`, `reviewer`, and `coordinator`.
+
+Every value in `entrypoints.newTask.writes` must exactly match one `writeScopes.*.path` entry. Do not rely on partial overlap.
+
+## Reference Bundle Pattern
+
+Use `resources.references` when the preset should preload common context for a group of tasks.
+
+```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` for Markdown that needs substitution. Use `source` for static files copied from the preset package. The created task should read like this: `task_plan.md` tells the agent which `REF-*` entries to read, `references/INDEX.md` explains why each file matters, and the actual `references/*.md` files contain the context.
+
+When `context.requiredReads` is set, Harness appends a `## Preset Required Reads` table to `task_plan.md`. Each row must resolve to the reference ID and exact `TARGET:<task-relative-reference-path>` that also appears in `references/INDEX.md`.
+
+## Artifact Bundle Pattern
+
+Use `resources.artifacts` for preset-provided support material that is not a source reference:
+
+```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
+```
+
+Do not confuse artifacts with evidence. Artifacts can be input packets or fixtures. Evidence proves what happened, such as `preset-audit.json`, `preset-manifest.json`, command output, or verification results.
+
+## Safety Rules
+
+- `writeScopes` must be as narrow as possible.
+- Generated files must stay under the created task directory.
+- A preset must not mutate source code, Git state, or global governance tables during `new-task`.
+- Do not add JavaScript for `new-task` behavior.
+- If behavior needs code, identify the missing reusable built-in processor and stop for design review.
+- Reference bundles are task-local snapshots. Do not silently mutate historical tasks when a preset package changes.
+- User-installed presets live in `~/.coding-agent-harness/presets/<preset-id>/`.
+
+## Creation Workflow
+
+1. Ask or infer the preset purpose, task family, target budget, task kind, required inputs, shared references, and evidence needs.
+2. For complex presets, open `references/complex-task-skeleton/README.md` and inspect the base task files the preset will overlay.
+3. Open `references/preset-package-skeleton.md` and copy only the files the preset actually needs.
+4. Create the preset directory with `preset.yaml`, templates, and resources.
+5. Keep task creation declarative: manifest inputs, `templateValues`, `metadata`, Markdown templates, `resources`, evidence declarations, and `writeScopes`.
+6. Run `harness preset check <path>`.
+7. Install with `harness preset install <path> --force` in a disposable or user-approved environment.
+8. Smoke test with `harness new-task <id> --budget <budget> --preset <preset-id> ... <target>`.
+9. For reference-bundle presets, create two different tasks from the same preset and verify both contain the same shared references but independent audit/evidence bundles.
+10. Run `harness status --json <target>`, `harness task-index --json <target>`, and `harness check --profile target-project <target>`.
+11. Inspect the generated `task_plan.md`, `references/INDEX.md`, and `artifacts/INDEX.md` manually before declaring success.
+
+## Quality Checklist
+
+- The preset name describes a task method, not a single task.
+- The generated task can be understood from files alone, without the original chat.
+- `task_plan.md` contains enough context for the next agent to know what to read first.
+- Every required read points to a real `REF-*` row.
+- Every `REF-*` row explains why that reference matters.
+- Every generated artifact has an `ART-*` row when artifacts are used.
+- The preset passes `preset check`, task creation, `status --json`, `task-index --json`, and target check.
+- A downstream agent can create a valid preset from this skill without editing Harness source.

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

@@ -0,0 +1,31 @@
+# Complex Task Skeleton Reference
+
+This folder is a standalone copy of the Harness complex task contract skeleton. Use it when designing a preset so the preset author can see the base files that `harness new-task --budget complex` creates before the preset overlay is applied.
+
+## Required Complex Task Files
+
+| File | Purpose |
+| --- | --- |
+| `brief.md` | Human-readable task summary and current context packet. |
+| `task_plan.md` | Goal, scope, budget, required files, acceptance criteria, and operating decisions. |
+| `execution_strategy.md` | Operating model, allocation, conflict control, evidence strategy, and subagent decisions. |
+| `visual_map.md` | Phase map, optional diagrams, completion state, evidence state, and blocking risk. |
+| `findings.md` | Findings, research notes, and unresolved risks. |
+| `lesson_candidates.md` | Task-local lesson candidate queue. |
+| `progress.md` | Execution log, decisions, handoff, and residuals. |
+| `review.md` | Agent review submission, adversarial review, evidence checked, and residual risk. |
+| `references/INDEX.md` | Complex task source/reference index. |
+| `artifacts/INDEX.md` | Complex task generated artifact/evidence index. |
+| `long-running-task-contract.md` | Optional add-on when the task is explicitly long-running. |
+
+## How A Preset Uses This Skeleton
+
+A preset should usually not replace these files. Harness creates the base task skeleton first. The preset then overlays method-specific content by:
+
+- appending task-plan guidance with `entrypoints.newTask.templates.taskPlanAppend`;
+- adding `metadata` lines that make scanner-visible context first-class;
+- writing `resources.references` and `resources.artifacts` into the task-local folders;
+- adding `context.requiredReads` so the next agent reads the right references before implementation;
+- generating audit/evidence files under a task-local `artifacts/preset` bundle.
+
+If a preset needs to change the structure of the complex task skeleton itself, do not hide that inside the preset. Update the Harness task templates or checker instead.

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

@@ -0,0 +1,12 @@
+# Artifacts Index
+
+Use this index for generated outputs that support the task but are not the source of truth.
+
+| ID | Type | Path | Summary | Produced By |
+| --- | --- | --- | --- | --- |
+| [artifact-id] | command / diff / fixture / screenshot / review / report | TARGET:path or URL:https://example.com | [why it exists] | coordinator |
+
+## Retention Notes
+
+- Keep artifacts that are needed to reproduce evidence or review decisions.
+- Remove or ignore temporary artifacts once their result is captured in `progress.md`.

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

@@ -0,0 +1,32 @@
+# {{TASK_TITLE}}
+
+## Brief
+
+## Task ID
+
+`{{TASK_ID}}`
+
+## Created
+
+{{DATE}}
+
+## Outcome
+
+State the user-visible or project-visible result this task must deliver.
+
+## Boundaries
+
+- In scope: files, behavior, documentation, or verification this task may change.
+- Out of scope: work that must not be folded into this task.
+- Stop conditions: uncertainty, risk, or missing access that requires coordinator or user review.
+
+## Execution Contract
+
+- Owner: coordinator
+- Lifecycle state: not_started
+- Required files: `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
+
+Replace this line with the first concrete action before implementation starts.

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

@@ -0,0 +1,71 @@
+# [Task Name] - Execution Strategy
+
+## Strategy Summary
+
+[Describe the execution approach, including why this operating model fits the risk and scope.]
+
+## Subagent Authorization
+
+Read this section at the start of the task and report the current authorization state before delegating.
+This is an audit record, not an execution sandbox.
+
+| Role | Status | Permission | Authorized By | Authorized At | Scope | Worktree / Branch | Reuse |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| reviewer subagent | allowed by default | read-only | harness task policy | task creation | current task review | n/a | allowed within this task |
+| worker subagent | not authorized | write only after user approval | pending | pending | pending | pending | allowed only within approved task/scope |
+
+## Subagent Delegation Decision
+
+At task start, the coordinator must make this decision from the user's goal, even if the user never mentions subagents.
+Do not expect the user to know what a subagent or worker is. If delegation would help, explain the benefit in plain language and ask for permission once.
+It is fine to say "subagent" or "worker" to the user; the important rule is that the agent must not wait for the user to ask for them.
+If the task is clearly split into independent slices, decide `ask-user` before implementation. If exact file paths are still unknown, first identify the paths, then immediately ask for the independent execution helper authorization.
+
+| Question | Decision | Reason | Next Action |
+| --- | --- | --- | --- |
+| Should a reviewer subagent be used? | yes / no | [why reviewer review helps or is unnecessary] | If yes, call a read-only reviewer without asking for extra permission. |
+| Would a worker subagent materially help? | no / ask-user / already-authorized | [parallel slice, independent implementation, focused investigation, or not useful] | If ask-user, ask directly: "This task is suitable for a worker subagent. Do you authorize me to assign one worker subagent to modify only [scope] in [worktree/branch] while I coordinate and review the result?" |
+
+## User Authorization Decision
+
+If the worker decision above is `ask-user`, implementation is blocked until this table records the user's answer.
+Allowed resolved states are `authorized`, `denied`, or `not-needed`. Do not leave this as `pending` after choosing `ask-user`.
+
+| Gate | State | Decided By | Decided At | Scope | Worktree / Branch | Notes |
+| --- | --- | --- | --- | --- | --- | --- |
+| worker subagent | pending | pending | pending | pending | pending | Fill only after directly asking the user. |
+
+## Operating Model
+
+- Model: solo / team / split-repo / program / waterfall / kanban / module-parallel
+- Primary executor: coordinator / worker / human
+- Shared sync owner: coordinator
+- Worktree required: yes / no
+- Review required: yes / no
+
+## Work Allocation
+
+| Role | Input Package | Write Scope | Handoff Required | Owner |
+| --- | --- | --- | --- | --- |
+| coordinator | task plan, strategy, roadmap | shared ledgers and integration | yes | [owner] |
+| worker | assigned slice | assigned files only | yes | [owner] |
+
+## Coordination Rules
+
+1. Shared files are coordinator-owned unless a lock is explicitly assigned.
+2. Workers update only assigned files and route shared-table changes through handoff.
+3. Parallel work must use non-overlapping write scopes.
+4. Integration runs final checks after worker commits are merged or applied.
+
+## Verification Strategy
+
+| Check | Command or Evidence | Required | Owner |
+| --- | --- | --- | --- |
+| Static check | [command or path] | yes / no | [owner] |
+| Unit test | [command or path] | yes / no | [owner] |
+| Integration or smoke | [command, URL, or log] | yes / no | [owner] |
+| Review | `review.md` / verifier output / n/a | yes / no | [owner] |
+
+## Closeout Rule
+
+Do not mark the task complete until required evidence is present, material findings are closed or accepted, and shared updates are either completed or assigned to the coordinator.

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

@@ -0,0 +1,24 @@
+# [Task Name] - Findings
+
+Use this file for defects, risks, unclear requirements, research notes, and review follow-up that may affect delivery.
+
+## Open Findings
+
+| ID | Severity | Finding | Evidence | Owner | Required Action | Status |
+| --- | --- | --- | --- | --- | --- | --- |
+
+Do not keep sample findings. Add rows only for real findings discovered during the task.
+
+## Resolved Findings
+
+| ID | Resolution | Evidence | Date |
+| --- | --- | --- | --- |
+
+Add rows only after a real finding is resolved or accepted with owner-routed risk.
+
+## Severity Guide
+
+- P0: Blocks release or risks data loss, security exposure, or production outage.
+- P1: Blocks the task goal or a required workflow.
+- P2: Material quality, maintainability, or evidence gap.
+- P3: Follow-up improvement that does not block closeout.

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

@@ -0,0 +1,70 @@
+# {{TASK_TITLE}} - Lesson Candidates
+
+This file is the task-local lesson candidate queue. Human review decides whether any candidate should stay task-local, be rejected, enter dry-run promotion, become a promoted lesson detail doc, or become a separate sedimentation task.
+
+## Candidate Status
+
+| Field | Value |
+| --- | --- |
+| Schema version | lesson-candidate-v1 |
+| Task-level status | pending-review |
+| Review gate | candidate-file-present |
+| Review decision | pending-human-review |
+| Promotion state | not-promoted |
+| Closeout token | pending |
+| Source task | {{TASK_ID}} |
+| Owner | coordinator |
+| Last updated | {{DATE}} |
+
+## Schema
+
+Allowed task-level status:
+
+- `missing`: candidate file is absent.
+- `pending-review`: candidate file exists, but human decision is not complete.
+- `no-candidate-accepted`: human accepted the agent's no-candidate reason.
+- `needs-promotion`: at least one candidate is queued for governance promotion.
+- `promoted`: all accepted candidates were promoted to the agreed governance target.
+- `rejected`: all candidates were rejected or archived with reasons.
+
+Allowed row status:
+
+- `ready-for-review`: agent believes this candidate may matter.
+- `needs-promotion`: human marked the candidate worth preserving through dry-run promotion or a follow-up sedimentation task.
+- `promoted`: maintenance CLI or an approved follow-up task promoted the candidate to the agreed governance target.
+- `rejected`: human rejected the candidate with a reason.
+
+Aggregation rule:
+
+- Any `ready-for-review` row keeps task-level status `pending-review`.
+- Any `needs-promotion` row sets task-level status `needs-promotion` unless another row is still `ready-for-review`.
+- All rows `promoted` sets task-level status `promoted`.
+- All rows `rejected` sets task-level status `rejected`.
+- A no-candidate task must use task-level status `no-candidate-accepted` and fill `No-Candidate Reason`.
+
+## Candidates
+
+| ID | Row Status | Title | Scope | Module Key | Detail Artifact | Boundary Reason | Why It Might Matter | Review Decision | Promotion Target | Conflict Check | Required Standard Update | Follow-up Task |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+
+## No-Candidate Reason
+
+Not decided yet. Fill this only when review accepts that the task produced no reusable lesson candidate.
+
+## Promotion Notes
+
+- If human review decides a candidate is worth preserving, mark the row `needs-promotion` and record the target governance location.
+- If a candidate is marked `needs-promotion`, write the full task-local detail artifact while the source task context is fresh, then link it in `Detail Artifact`.
+- Use `Scope` values `task`, `module`, or `global`; module-scoped candidates must fill `Module Key`.
+- If human review rejects a candidate, mark the row `rejected` and keep the reason in the review decision.
+- `needs-promotion` does not block task closeout, but it must remain visible in the maintenance queue and closeout record.
+- Default promotion behavior is dry-run or follow-up-task first. Do not write a shared Lessons table; accepted candidates become promoted lesson detail docs.
+- A sedimentation task must classify scope, check conflicts against existing lessons and standards, propose the target change, and report verification before applying.
+
+## Queue Routing
+
+| Queue | When this task enters it | Exit condition |
+| --- | --- | --- |
+| Lessons | Any candidate is `ready-for-review` or `needs-promotion`. | Human rejects it, keeps it task-local, creates a sedimentation task, or approves promotion. |
+| Missing Materials | The file is absent, has invalid status, or lacks a required no-candidate reason. | Agent repairs the candidate file. |
+| Confirmed / Finalized | Human review is confirmed but a candidate still has deferred governance work. | Follow-up task or dry-run decision is recorded. |

package/skills/preset-creator/references/complex-task-skeleton/long-running-task-contract.md

@@ -0,0 +1,76 @@
+# [Task Name] - Long-Running Task Contract
+
+## Goal
+
+[State the single main problem this loop must close.]
+
+## Scope
+
+### In Scope
+
+- [Allowed directories, modules, or capability surfaces]
+
+### Out of Scope
+
+- [Items explicitly excluded from this loop]
+
+### Shared Files and Conflict Risk
+
+- [Shared files that may conflict with other work, or none]
+
+## Primary Caller / Entry
+
+- Primary caller: [CLI / local agent / UI / API / automation / integration / other]
+- Entries this task must support: [list]
+- Entries explicitly not required: [list]
+
+## Permission Boundaries
+
+- Continuous execution allowed: yes / no
+- Automatic review/fix/test loop allowed: yes / no
+- Reviewer or subagent allowed: yes / no
+- Must pause before: [high-risk actions]
+
+## Required Loop
+
+1. Re-read the goal, scope, and current findings.
+2. Choose the smallest complete fix for the current finding or phase.
+3. Implement within the allowed write scope.
+4. Run required verification.
+5. Update `progress.md` and `findings.md`.
+6. Run review when required and update `review.md`.
+7. Continue, stop, or pause based on the stop and pause conditions below.
+
+## Reviewer / Subagent Contract
+
+- Reviewer scope: [files / modules / problem domain]
+- Reviewer output: `review.md`
+- Worker allowed to edit code: yes / no
+- If a worker may edit, handoff must include worktree path, branch, commit SHA, checks, files changed, and residual risks.
+
+## Evidence
+
+- [ ] Static checks: [command]
+- [ ] Unit tests: [command]
+- [ ] Integration or smoke tests: [command]
+- [ ] Runtime verification: [URL / command / log]
+- [ ] Review report: `review.md` / n/a
+- [ ] Residual risks recorded: yes / no
+- [ ] Lesson candidate review recorded: `lesson_candidates.md` uses `no-candidate-accepted`, `needs-promotion`, `promoted`, or `rejected`
+
+## Stop Conditions
+
+- [ ] Goal is met.
+- [ ] Scope was not exceeded.
+- [ ] Required tests and regression gates pass or have documented waivers.
+- [ ] Runtime, console, and request errors are clear or classified as accepted-risk with owner rationale.
+- [ ] Review has no open P0/P1 material findings.
+- [ ] Residual risks are routed to an owner and do not block the goal.
+
+## Pause Conditions
+
+- [ ] Goal or scope becomes invalid.
+- [ ] High-risk product, architecture, security, or data decision is required.
+- [ ] Unknown uncommitted changes conflict with this work.
+- [ ] Environment, permission, quota, or external dependency blocks progress.
+- [ ] Reviewer finding changes task direction.

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.]