Harness Maintenance Pipeline

Harness Maintenance Pipeline

One on-demand entry point for project maintenance. Runs the checks that are actually overdue, triages what needs attention, and asks you — in plain text — which to fix. A thin wrapper over harness maintenance run; it owns no state of its own.

When to Use

• You want to answer "which maintenance did I forget to run?" without standing up an orchestrator.
• At a milestone or before a release, to sweep overdue health checks (dead code, doc drift, dependency health, security, hotspots, project health).
• When you want a report first and an explicit, opt-in fix step — never a surprise PR.
• NOT for running a single known check — call that skill or harness maintenance run --only <id> directly.
• NOT for the autonomous cron fix-and-PR path — that is the orchestrator scheduler's job; this is the human-invoked, report-first path.

What this skill does NOT do

• It does not implement any maintenance check, scheduler, or registry — the CLI and the existing 22-task registry are the single source of truth.
• It does not write artifacts. The CLI writes .harness/maintenance/last-run-summary.json and records history; this skill only reads and relays.
• It does not open PRs. Fixes are opt-in via the explicit fix step; when a backend is configured, --fix dispatches a real agent that commits to the worktree (no PR). When no backend is configured it honestly skips (see Phase 3 / FIX).

Process

Phase 1: SWEEP — run the overdue report

1. Run the report-mode sweep and capture stdout:

   harness maintenance run --json
   

   No flags = overdue, sweep-eligible tasks only, report mode (no PRs). Capture both stdout (the JSON report) and the exit code.

2. Parse stdout as a ConsolidatedReport:

   // shape emitted by the CLI (packages/cli/src/commands/maintenance-run.ts)
   {
     generatedAt: string;
     mode: 'report' | 'fix';
     fix: boolean;
     exitCode: 0 | 1;
     tasks: Array<{
       taskId: string;
       status: 'success' | 'failure' | 'skipped' | 'no-issues';
       findings: number;       // a COUNT — there is no per-finding severity
       fixed: number;
       prUrl: string | null;
       summary: string;        // 'clean' | `${n} finding(s)` | error text
       error?: string;
     }>;
     overdueNowCurrent: string[];
   }
   

   If capturing stdout is awkward, read the same object from .harness/maintenance/last-run-summary.json with the Read tool.

3. Read the exit code: 0 = the sweep completed (findings are NOT failures); 1 = at least one check failed to execute; 2 = invalid invocation (a bug in how this skill called the CLI — fix the invocation, do not report it as a finding).

4. If tasks is empty, tell the human "All maintenance is current — nothing overdue." and stop. Do not invent work.

Phase 2: TRIAGE — present a human-readable summary

There is no per-finding severity in the report, so triage by status then findings count (rows arrive pre-sorted failures-first, then findings-descending). Bucket the tasks:

• Failed to execute — status === 'failure'. The check itself crashed; surface summary/error. These are the most urgent: a finding you cannot see is worse than one you can.
• Needs attention — findings > 0 (and not a failure). Order by findings descending. Derive a coarse domain from the task id (e.g. dead-code, doc-drift, dependency-health, security, hotspots, project-health).
• Skipped (couldn't run) — status === 'skipped'. A precondition gate was not met, so the check never ran — it is NOT clean, it has simply told you nothing. Report these distinctly from clean tasks so the human knows coverage was incomplete (and can decide whether the precondition is worth satisfying). Summarize as a count and, if useful, surface summary for why it was gated.
• Clean — status is no-issues/success with findings === 0. The check ran and found nothing. Summarize as a count ("8 checks clean"); do not enumerate unless asked. Do NOT fold skipped tasks in here — a gated check that never ran is not a clean result.

Render a compact summary, for example:

Maintenance sweep (report mode) — 18 overdue tasks ran, exit 0

Failed to execute (1):
  stale-constraints   — check crashed: <summary>

Needs attention (3):
  dead-code           — 12 finding(s)
  doc-drift           —  4 finding(s)
  dependency-health   —  1 finding(s)

Skipped — couldn't run (1): license-audit (precondition not met)

Clean (13): project-health, hotspots, security, …

If overdueNowCurrent is non-empty, add a one-line footer: "N tasks were overdue and are now marked current."

Phase 3: FIX — ask in plain text, then opt in

1. Ask the human in plain text, in your own reply. Do NOT use emit_interaction and do NOT use AskUserQuestion for this — those channels do not reliably reach the human (an emit_interaction ask collapses to "Called harness" and the human never sees the question). Write the question as ordinary text, listing the actionable task ids (the "Failed to execute" and "Needs attention" buckets) and asking which, if any, to fix. For example:

   These tasks have findings: dead-code (12), doc-drift (4), dependency-health (1). Which would you like me to fix? Reply with a comma-separated list of task ids, "all", or "none".

   Then stop and wait for the human's reply. Do not proceed to a fix without an explicit answer.

2. If the human picks tasks, re-invoke the CLI in fix mode, scoped to exactly those ids — and capture both streams separately:

   harness maintenance run --only <comma,separated,ids> --fix --json
   

   stdout stays a clean, parseable ConsolidatedReport (parse it as JSON, same shape as the sweep). Any honesty notice is written to stderr, NOT stdout — so capture stderr too (e.g. redirect to a separate file/buffer) and inspect it. If you only read stdout you will silently drop the notice; if you merge stderr into stdout you will break JSON.parse. Keep them apart: JSON ← stdout, notice ← stderr.

3. Relay the result honestly. --fix threads fix mode through the real agent dispatcher: when a backend is configured for the default maintenance backend, the agent runs and commits its fixes directly to the worktree — there is no PR (prUrl stays null), and fixed is the real commit count. When no backend is configured (a plain checkout with no agent.backends in harness.orchestrator.md), --fix does not crash and does not pretend to work — it skips dispatch and prints this notice to stderr (which is why step 2 captures stderr separately):

   --fix: no agent backend configured for maintenance dispatch — dispatch was skipped and nothing was fixed. Configure agent.backends in harness.orchestrator.md (and maintenance.aiBackend), or run maintenance via the orchestrator.

   Inspect the captured stderr for that notice and, if present, surface it verbatim. Report what the CLI actually did (the stdout report's fixed counts; prUrl is always null — there is no PR) — never claim a fix was applied or a PR opened when the report does not show one.

4. If the human picks "none", stop. The report stands on its own.

Harness Integration

• harness maintenance run --json — the report-mode sweep this skill wraps. Runs overdue, sweep-eligible tasks only and emits the ConsolidatedReport to stdout (also written to .harness/maintenance/last-run-summary.json). This is the single entry point — the skill adds no execution path of its own.
• harness maintenance run --only <ids> --fix --json — the opt-in fix leg, scoped to the ids the human picked. Threads mode: 'fix' through the same TaskRunner, using the real agent dispatcher. Capture stdout (the JSON report) and stderr separately: when no agent backend is configured it prints the honest no-backend skip notice to stderr (stdout stays clean JSON) — inspect that captured stderr and relay any notice verbatim.
• harness maintenance list / harness maintenance show <id> — inspect the registry (the 22-task source of truth) when the human wants to know what a task id means before choosing to fix it.
• Read tool on .harness/maintenance/last-run-summary.json — the documented fallback parse path if capturing --json stdout is awkward on a given platform. The skill never writes this file; the CLI owns it.

Gates

• Plain-text ask only. The "which to fix?" question must be ordinary text in your reply. Never route it through emit_interaction or AskUserQuestion.
• Report before fix, always. Never pass --fix on the first sweep. Fix is opt-in after the human sees the report and chooses.
• No invented findings. Report only what the ConsolidatedReport contains. If tasks is empty, say so and stop.
• No self-persistence. Do not write .harness/maintenance/* or any report file — the CLI owns artifacts.
• Honest fix status. Relay what the CLI reports: real fixed counts when a backend dispatched, or the no-backend skip notice (if it appears on stderr) when it did not. prUrl is always null — the agent commits to the worktree; never imply a PR was opened.

Success Criteria

• Ran harness maintenance run --json, parsed the consolidated report, and read the exit code.
• Presented a triaged summary bucketed by status (failed / needs-attention / clean) and ordered by findings count.
• Asked the human in plain text which tasks to fix, and waited for a reply.
• On opt-in, re-invoked --only <ids> --fix and relayed the result (real fixed counts, or the honest no-backend skip notice if it appeared) verbatim.
• Wrote no files of its own.

Examples

Example: Milestone sweep with mixed results

The human invokes the skill before tagging a release.

1. SWEEP: Run harness maintenance run --json. Exit code 0; tasks has 18 rows; overdueNowCurrent lists 18 ids.

2. TRIAGE: Bucket the pre-sorted rows:

   Maintenance sweep (report mode) — 18 overdue tasks ran, exit 0
   
   Failed to execute (1):
     stale-constraints   — check crashed: cannot read .harness/constraints.json
   
   Needs attention (3):
     dead-code           — 12 finding(s)
     doc-drift           —  4 finding(s)
     dependency-health   —  1 finding(s)
   
   Clean (14): project-health, hotspots, security, …
   18 tasks were overdue and are now marked current.
   

3. FIX (plain-text ask): In the reply, write: "These tasks have findings: dead-code (12), doc-drift (4), dependency-health (1), plus stale-constraints failed to execute. Which would you like me to fix? Reply with a comma-separated list of task ids, "all", or "none"." Then stop and wait.

4. The human replies dead-code,doc-drift. Run harness maintenance run --only dead-code,doc-drift --fix. With a backend configured, the agent dispatches and commits its fixes to the worktree — report the real fixed counts from the report (prUrl: null — there is no PR). If no backend is configured, the CLI prints to stderr: --fix: no agent backend configured for maintenance dispatch — dispatch was skipped and nothing was fixed. Configure agent.backends in harness.orchestrator.md (and maintenance.aiBackend), or run maintenance via the orchestrator. Relay that verbatim and report fixed: 0, prUrl: null — do not claim a fix or PR.

Example: Nothing overdue

Run harness maintenance run --json. On the nothing-overdue happy path stdout is still a parseable ConsolidatedReport whose tasks is an empty array (tasks: [], exitCode: 0) — NOT a plain All maintenance current. sentinel (that human string is emitted only on the non---json path). So JSON.parse(stdout) succeeds; read tasks.length === 0. Tell the human "All maintenance is current — nothing overdue." and stop. Do not invent work or run --fix.

Rationalizations to Reject