better-harness

Better Harness

Review the coding-agent system: context, execution, control, feedback, and learning; keep Sessions, project, and Agent assets independent.

Step 1: Resolve Scope and Collect the Evidence Bundle

Route:

• <better-harness-fix-output>: Finding-bound Fix.
• No callback plus leading fix, repair, or \u4fee\u590d: Manual Direct Fix.
• Review/evaluation/reporting or mixed review-and-fix: Step 1.

Resolve the Skill path, <better-harness-root> as ../.., a supported <node>, and <cli> as <node> <better-harness-root>/scripts/better-harness.mjs. Stop if any owner is missing; never select another cache or runtime by search order.

Resolve absolute target, decision, acceptance boundary, risks, locale (request language by default), output mode, provider, and depth. Quick uses three items and 7 days; normal uses five and 30 days. Default Qoder/Cursor to durable Canvas and other rendering hosts to HTML. Providers without REPORT_RENDERING proceed only inline or no-files and must not create HTML, Markdown, or Canvas output. Keep providers separate. Use the current one unless project-wide review explicitly authorizes multiple supported providers. Qoder project Memory title metadata is part of the selected workspace baseline. Memory bodies, Codex Memory, Qoder global Memory, user-home, raw Session, installed-plugin, marketplace, and historical-insight access require explicit scope.

Before delegation, collect one versioned evidence bundle per authorized provider:

<cli> harness evidence-bundle --platform <provider> --workspace <target> --cwd <effective-cwd> --language <locale> --depth <quick|normal> --since <window-start> --until <window-end> --format json [--include-memories] [--include-user-home] [--canvas-out <run-dir>/canvas.json]

Use --canvas-out only for Qoder/Cursor durable reports. For Qoder, keep the default project Memory-title scan; --include-user-home widens it to authorized global Memory/config and other user assets. For Codex, Memory metadata requires --include-memories; user/global or installed-Plugin metadata requires --include-user-home. Apply both when both scopes are authorized. Neither flag authorizes Memory bodies.

It freezes topology, provider, window, depth, limit, and authority. Before delegation, read bundle.context.topology.target; report kind, route, and packageRoute (memberRoute or null). Providers must agree. It returns sessionEvidence, projectHarness, agentCustomize, and the lead envelope. Agent Customize holds bounded lint, inventory, and integrity envelopes from one shared asset snapshot. Keep lane/stage status and providers distinct. Use the individual session-analysis facts, core-change-watch evidence-pack, coding-agent-practices asset-baseline, or harness analyze command only to diagnose a named unavailable or evidence-loss stage; do not substitute diagnostic output into the bundle or rerun all owners. Counts for Rules, Skills, MCP, Memory, Agents, Hooks, Commands, Workflows, and Plugins only route inspection. Zero or high counts never create findings or scores. A normal Qoder report with project Memories blocks when the integrity stage is unavailable; do not replace the missing review with an unobserved disposition.

If the provider discovers or the user supplies a historical insight source, the lead may inspect only a few authorized architecture/history notes. Never assume or search a conventional path; notes cannot prove current behavior, configured capability, or effectiveness.

Step 2: Run Three Independent Evidence Passes

Launch exactly three fresh, read-only agents in parallel. In Codex use spawn_agent with fork_turns: "none"; otherwise run the same briefs locally and independently. No evidence agent may delegate.

2.1 Session Evidence

The lead takes the provider-labelled facts envelopes from bundle.lanes.sessionEvidence.data, whose production collector is routed by Sessions Diagnostics, using only the production facts route. Do not pass the complete bundle, collection reference, debug output, or raw sessions to Agent 1.

Give Agent 1 only the provider-labelled facts envelopes, the compact Step 1 asset counts needed to notice zero Skills, and the resolved scope. Require it to read Session Evidence and conditionally read Repeated Workflow Discovery when repeated procedure demand is in scope. It must not inspect the project, configured assets, raw sessions, or another brief.

2.2 Project Harness Evidence

Give Agent 2 only the target, scoped history/current-change boundary, bundle.lanes.projectHarness.data, decision, risks, and owner limit. Require it to read Project Harness Evidence. It must not receive Session or Agent Customize conclusions.

2.3 Agent Customize Evidence

Give Agent 3 only bundle.lanes.agentCustomize.data with its provider-labelled lint, inventory, and integrity envelopes; asset authority; decision; risks; and owner limit. Require it to read Agent Customize Evidence. It consumes the deterministic envelopes and must not rerun their commands or receive Session/Project conclusions.

Each agent follows its reference-local free-form return contract: normally three to five candidates, up to three in quick mode, and fewer when evidence is sparse. Specialists never assign final severity or scores.

While they run, use only bundle.lead.data as the lead analyzer result. The bundle maps --include-user-home to the analyzer's global-capability boundary; this preserves authorized MCP, Plugin, Skill, Hook, and Memory counts without authorizing content reads or proving use.

Stop if the bundle is failed, the lead lane is unavailable, or its data omits evidence or summaryFacts. In quick mode a partial bundle lowers confidence and every unavailable specialist remains explicit; in normal mode any unavailable or partial specialist lane blocks the report. This evidence pass has a hard cap of three delegated agents.

Step 3: Lead Reconciliation and Regrading

Read Harness Findings Input for field roles and Agent Work Loop for the five dimensions, checks, evidence states, scoring, and Learning Capture rules. Replace all example content. Never derive the contract from prior reports, Memory, recommend files, or validators.

Perform one reconciliation. Start by retaining every specialist candidate. Merge only candidates with the same target, observed consequence, owner, and repair route; preserve independent consequences even when they share a broader theme. Keep a working reason for every unsupported or deferred candidate. Never drop an eligible finding to reach five rows, shorten the report, simplify a score, or match the three priority moves. Then the lead alone:

• validates the consequence, cause chain, smallest owner, evidence boundary, confidence, and verifier;
• assigns final severity and one primary Agent Work Loop check;
• derives conservative dimension scores independently from findings count;
• retains disagreements and unavailable evidence at low confidence;
• writes every distinct supported finding and freezes final severity and dimension scores before shaping priority moves, repair prompts, or reader copy.

Before drafting, read Findings Quality Gates and apply its eligibility, consistency, privacy, asset, candidate-promotion, and repair-prompt checks directly. For repeated procedure or knowledge demand, also read Asset Demand Reconciliation.

Do not author summary.suggestions in a new report. Promote a suggestion candidate to an ordinary Low finding only when it passes the same consequence, owner, evidence, output, verifier, and repair-prompt gates as every finding; otherwise keep it deferred in the working reconciliation.

After findings and dimension scores are frozen, select exactly one support track from the evidence and requested outcome. The parenthetical ranges are user-journey labels, never score thresholds:

• Bootstrap (0 -> 1): initial guidance is explicitly requested, or retained findings establish a missing foundational navigation, validation, or risk route.
• Operationalize (1 -> 60): relevant mechanisms exist, but retained findings show they are not wired into ordinary work or exercised through an outcome.
• Optimize (60 -> 100): sufficiently complete Session evidence contains at least two distinct comparable Task Episodes for the repeated goal or friction.
• Undetermined: the evidence required to select a track is unavailable.

Read only the selected track: Bootstrap Support, Operationalize Support, or Optimize Support. A track may shape at most three priority moves, repair prompts, and reader copy for already-supported findings. It must not add a finding, change severity, rescore a dimension, add a report field, or expand evidence and mutation authority.

For a durable report, draft findings.json only after the three evidence agents finish. Do not launch a fourth review agent. The lead applies the quality gates once, preserves all eligible findings, and fixes any machine-validation failure before rendering.

Report Output — Step 4: Render an Authorized Report

Inline analysis writes nothing. After lead checks pass, treat the draft as the one final findings.json, then render and validate it once:

Qoder/Cursor: <mode>=<provider>-canvas; <host-root>=<target>/.<provider>/better-harness
Other providers: <mode>=html; <host-root>=<target>/.<provider>/better-harness
<cli> harness render --findings <run-dir>/findings.json --mode <mode> --out <host-root> --run-dir <run-dir> --target <target> --validate --json

Qoder/Cursor analysis owns adjacent canvas.json; do not copy its summaryFacts into findings. HTML keeps analyzer summaryFacts verbatim. Succeed only on status: pass and return the exact paths reported by render. Never hand-write Canvas, Markdown, or HTML.

Finish with one compact sentence: <count> findings. [Open the report](<renderer-path>). Link the renderer-reported primary report; never return inline-code paths, a bare directory, or an output-file inventory.

Step 5: Follow Up

• Finding-bound repair uses Finding-bound Fix; a separate independent post-fix agent may update verified finding state and Repair Progress; Loop Effectiveness waits for comparable later Task Episodes.
• Usage/model questions use session-analysis usage-summary once.
• Repeated work continues through Loop Discovery.
• Routes: Agent Customize, Core Change Watch, Report Routing, Source Review.

The durable route authorizes only renderer-owned artifacts in its host root. Other creation, activation, mutation, cleanup, scheduling, external writes, and high-risk access require task-local authority. If an owner or value is unresolved, stop with the condition to resume; do not invent a substitute artifact or inspect internal validators.