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.