coding-agent-harness 1.0.2 → 1.0.5

package/scripts/lib/task-tombstone-commands.mjs

@@ -0,0 +1,140 @@
+import fs from "node:fs";
+import path from "node:path";
+import {
+  normalizeTarget,
+  nowTimestamp,
+  readFileSafe,
+  toPosix,
+  datePrefix,
+} from "./core-shared.mjs";
+import { collectTasks } from "./task-scanner.mjs";
+import {
+  beginGovernanceSync,
+  commitGovernanceSync,
+  releaseGovernanceSync,
+} from "./governance-sync.mjs";
+
+export function supersedeTask(targetInput, oldRef, { by = "", reason = "" } = {}) {
+  if (!by) throw new Error("task-supersede requires --by <new-task-id>");
+  const target = normalizeTarget(targetInput);
+  const oldTask = resolveTask(target, oldRef);
+  const newTask = resolveTask(target, by);
+  const governanceContext = beginGovernanceSync(target, { operation: `task-supersede ${oldTask.id}` });
+  try {
+    writeTombstone(target, oldTask, {
+      State: "superseded",
+      "Superseded By": newTask.id,
+      Reason: reason || "superseded",
+      Operator: "coordinator",
+      Timestamp: nowTimestamp(),
+      "Reopen Eligible": "yes",
+      "Archive Eligible": "no",
+    });
+    appendProgress(target, oldTask, `task-supersede: superseded by ${newTask.id}`, reason || "superseded");
+    appendSupersedes(target, newTask, oldTask.id);
+    const commit = commitGovernanceSync(contextFor(target, governanceContext), taskPaths(target, oldTask, newTask), {
+      message: `chore(harness): supersede task ${oldTask.id}`,
+    });
+    return { taskId: oldTask.id, supersededBy: newTask.id, reason: reason || "superseded", governance: { commit } };
+  } finally {
+    releaseGovernanceSync(governanceContext);
+  }
+}
+
+export function softDeleteTask(targetInput, taskRef, { reason = "" } = {}) {
+  const target = normalizeTarget(targetInput);
+  const task = resolveTask(target, taskRef);
+  return writeDeletionState(target, task, "soft-deleted", reason || "soft-delete", "task-delete --soft");
+}
+
+export function archiveTask(targetInput, taskRef, { reason = "" } = {}) {
+  const target = normalizeTarget(targetInput);
+  const task = resolveTask(target, taskRef);
+  return writeDeletionState(target, task, "archived", reason || "archive", "task-archive");
+}
+
+export function reopenTask(targetInput, taskRef, { reason = "" } = {}) {
+  const target = normalizeTarget(targetInput);
+  const task = resolveTask(target, taskRef);
+  const governanceContext = beginGovernanceSync(target, { operation: `task-reopen ${task.id}` });
+  try {
+    const taskPlanPath = path.join(target.projectRoot, task.taskPlanPath.replace(/^TARGET:/, ""));
+    const content = readFileSafe(taskPlanPath);
+    const next = content.replace(/\n##\s*(?:Task Tombstone|任务墓碑)\s*$[\s\S]*?(?=^##\s+|(?![\s\S]))/im, "");
+    fs.writeFileSync(taskPlanPath, next.endsWith("\n") ? next : `${next}\n`);
+    appendProgress(target, task, "task-reopen", reason || "reopened");
+    const commit = commitGovernanceSync(governanceContext, taskPaths(target, task), {
+      message: `chore(harness): reopen task ${task.id}`,
+    });
+    return { taskId: task.id, deletionState: "active", reason: reason || "reopened", governance: { commit } };
+  } finally {
+    releaseGovernanceSync(governanceContext);
+  }
+}
+
+function writeDeletionState(target, task, deletionState, reason, action) {
+  const governanceContext = beginGovernanceSync(target, { operation: `${action} ${task.id}` });
+  try {
+    writeTombstone(target, task, {
+      State: deletionState,
+      Reason: reason,
+      Operator: "coordinator",
+      Timestamp: nowTimestamp(),
+      "Reopen Eligible": "yes",
+      "Archive Eligible": deletionState === "archived" ? "yes" : "no",
+    });
+    appendProgress(target, task, action, reason);
+    const commit = commitGovernanceSync(governanceContext, taskPaths(target, task), {
+      message: `chore(harness): ${action.replace(/\s+/g, " ")} ${task.id}`,
+    });
+    return { taskId: task.id, deletionState, reason, governance: { commit } };
+  } finally {
+    releaseGovernanceSync(governanceContext);
+  }
+}
+
+function taskPaths(target, ...tasks) {
+  return [...new Set(tasks.flatMap((task) => [task.taskPlanPath, task.progressPath]).filter(Boolean).map((item) => toPosix(item.replace(/^TARGET:/, ""))))];
+}
+
+function contextFor(_target, context) {
+  return context;
+}
+
+function resolveTask(target, ref) {
+  const normalized = String(ref || "").trim();
+  const matches = collectTasks(target).filter((task) => {
+    const bare = datePrefix.test(task.shortId) ? task.shortId.replace(datePrefix, "") : task.shortId;
+    return task.id === normalized || task.shortId === normalized || task.id.endsWith(`/${normalized}`) || bare === normalized;
+  });
+  if (matches.length === 1) return matches[0];
+  if (matches.length > 1) throw new Error(`Ambiguous task reference: ${ref}`);
+  throw new Error(`Task not found: ${ref}`);
+}
+
+function writeTombstone(target, task, fields) {
+  const taskPlanPath = path.join(target.projectRoot, task.taskPlanPath.replace(/^TARGET:/, ""));
+  const content = readFileSafe(taskPlanPath).replace(/\n##\s*(?:Task Tombstone|任务墓碑)\s*$[\s\S]*?(?=^##\s+|(?![\s\S]))/im, "");
+  const block = ["", "## Task Tombstone", "", "| Field | Value |", "| --- | --- |", ...Object.entries(fields).map(([key, value]) => `| ${key} | ${escapeCell(value)} |`), ""].join("\n");
+  fs.writeFileSync(taskPlanPath, `${content.trimEnd()}\n${block}`);
+}
+
+function appendSupersedes(target, task, oldId) {
+  const taskPlanPath = path.join(target.projectRoot, task.taskPlanPath.replace(/^TARGET:/, ""));
+  const content = readFileSafe(taskPlanPath);
+  if (/^Supersedes\s*[:：]/im.test(content)) {
+    fs.writeFileSync(taskPlanPath, content.replace(/^Supersedes\s*[:：]\s*(.*)$/im, (_m, current) => `Supersedes: ${[current, oldId].filter(Boolean).join(", ")}`));
+    return;
+  }
+  fs.writeFileSync(taskPlanPath, `${content.trimEnd()}\nSupersedes: ${oldId}\n`);
+}
+
+function appendProgress(target, task, action, reason) {
+  const progressPath = path.join(target.projectRoot, task.progressPath.replace(/^TARGET:/, ""));
+  const relative = toPosix(path.relative(target.projectRoot, progressPath));
+  fs.appendFileSync(progressPath, `\n\n## Tombstone Log\n\n- ${nowTimestamp()} ${action}: ${escapeCell(reason)} (${relative})\n`);
+}
+
+function escapeCell(value) {
+  return String(value || "").replace(/\r?\n/g, " ").replaceAll("|", "\\|").trim();
+}

package/scripts/postinstall.mjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+
+import { seedBundledPresets } from "./lib/harness-core.mjs";
+
+if (process.env.CODING_AGENT_HARNESS_SKIP_POSTINSTALL === "1") process.exit(0);
+
+try {
+  const result = seedBundledPresets({ scope: "user" });
+  const changed = result.created + result.overwritten;
+  const summary = changed > 0 ? `${changed} bundled presets installed` : `${result.skipped} bundled presets already present`;
+  console.log(`coding-agent-harness postinstall: ${summary} at ${result.target}`);
+} catch (error) {
+  console.warn(`coding-agent-harness postinstall: preset seed skipped (${error.message})`);
+}

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,43 @@
+# {{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.
+
+## Scaffold Provenance
+
+| Field | Value |
+| --- | --- |
+| Created By | {{SCAFFOLD_CREATED_BY}} |
+| Command Shape | {{SCAFFOLD_COMMAND}} |
+| Created At | {{SCAFFOLD_CREATED_AT}} |
+| Budget | {{SCAFFOLD_BUDGET}} |
+| Template Source | {{SCAFFOLD_TEMPLATE_SOURCE}} |
+| Exception Reason | {{SCAFFOLD_EXCEPTION_REASON}} |

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.