Spec: Issue 181 Lint Feedback Adoption

Issue 224 supersession

The approved managed lint spec supersedes AC-006's nearest-config discovery and the matching Oxlint execution constraint for Harness-managed routes. Saved lint.scopes/lint.exclude select software ownership; each owner has one explicit effective oxlint.config.ts and local-tool route with nested discovery disabled. Root dispatch, package/CI commands, Lefthook, edited-file verification, and update validation share that authority. Wiki and embedded projects are excluded; ordinary tests remain covered.

The file-only safe-fix lifecycle, bounded retries, provider capability limits, local typed settings, project-policy preservation, and findings-versus-operational failure distinction remain required. Compatible authored JSON/JSONC remains at its original project-owned path; oxlint.project.json is a convention for new policy. Represented project thresholds survive; new generated lint retains --max-warnings 0, independently of diagnostic severity.

The original criteria, tool tuple, repair commit, diagnostic counts, and manual provider proof limits below remain historical evidence. This supersession records accepted issue 224 behavior; it does not establish its final T6 adoption/health or T7 parity proof.

Context

Harness Intelligence installs a managed post-edit hook. For JavaScript and TypeScript, that hook formats the edited file and runs Oxlint, but it discards Oxlint's structured diagnostics. The active agent therefore receives a generic failure instead of the exact findings it can repair in the same turn.

Issue 181 records a related scaffold failure in Collective Intelligence. Repair commit 1a9927873 restored nested-config discovery, limited typed lint settings to the owning workspace, removed an unsupported plugin, and separated lint and format checks. The measured lint inventory fell from 54,451 to 51,187 diagnostics. That proves the generated hierarchy caused material noise; it does not prove Ultracite alone caused the remaining diagnostics.

Ultracite exposes rules, a reusable skill, generated hooks, ordinary check and fix commands, and agent-assisted fix --codex and fix --claude modes. Harness will use the bounded repair protocol without installing Ultracite's rules, skill, or generated hooks into default context packs.

Non-Goals

• Automatically clean the historical 51,187-diagnostic baseline.
• Run a project-wide fix after every agent edit.
• Invoke ultracite fix --codex or another nested agent automatically.
• Use dangerous Oxlint fixes or ultracite fix --unsafe automatically.
• Add blanket suppressions to make adoption pass.
• Rewrite arbitrary project-owned lint configurations during scaffold/update.
• Promise current-turn continuation for providers without a documented seam.
• Remove unrelated lint rules, settings, plugins, or dependencies.
• Support additional languages or lint providers in this delivery.

User Stories

US-001: Repair the edited file in the active turn

As an agent in a Harness-managed repository, I need exact lint and format feedback for the file I changed so I can repair it before continuing.

US-002: Receive a predictable generated lint hierarchy

As a repository operator, I need generated and adopted Oxlint configuration to respect workspace ownership so root and workspace lint runs apply the intended policy.

US-003: Receive provider-native feedback

As an agent using Codex, Claude, Cursor, or OpenCode, I need the same diagnostic facts delivered through the strongest response contract my provider supports.

US-004: Preview lint impact during adoption

As an operator running hi update, I need candidate lint debt exposed before publication without existing debt making adoption impossible.

US-005: Run deliberate bounded cleanup

As an operator repairing historical debt, I need documented Ultracite commands to check, diagnose, fix, or delegate only targets I selected.

Acceptance Criteria

• AC-001: After a supported JavaScript or TypeScript edit, the managed hook resolves the owning workspace, formats the exact edited file, and applies only safe Oxlint fixes to that file.

  • Covers: US-001

• AC-002: A verification pass emits a normalized result that preserves each remaining finding's file, rule, severity, line, column, message, and available help or documentation URL, while distinguishing tool and configuration failures from lint findings.

  • Covers: US-001, US-003

• AC-003: A clean verification emits no repair request; a non-clean verification gives the active provider actionable findings for the affected file before its workflow continues.

  • Covers: US-001, US-003

• AC-004: The same session, file, and unchanged diagnostic fingerprint can request repair no more than three times, after which the hook reports exhaustion and does not restart the loop.

  • Covers: US-001

• AC-005: Automatic repair never uses dangerous fixes, adds suppressions, edits lint configuration, or changes an unrelated file.

  • Covers: US-001

• AC-006: Generated lint scripts and configurations preserve nearest-config discovery, keep formatting checks separate from lint checks, and enable typed settings only from the workspace that owns them.

  • Covers: US-002

• AC-007: Harness-owned policy retains the global disables func-names, func-style, and sort-keys; retains no-unused-vars: "warn" where already owned; removes no-shadow, no-underscore-dangle, unicorn/consistent-function-scoping, import/no-unassigned-import, unicorn/no-array-sort, and unicorn/no-array-reverse; and preserves all unrelated project-owned settings.

  • Covers: US-002

• AC-008: The installed and generated lint toolchain resolves exactly @effect/tsgo@0.39.0, oxlint@1.80.0, oxlint-tsgolint@7.0.2001, typescript@7.0.2, ultracite@7.10.7, and oxfmt@0.66.0, and a live Effect rule produces a structured Oxlint diagnostic after the lint-only patch step.

  • Covers: US-002

• AC-009: Codex receives remaining findings through its native synchronous PostToolUse response with decision: "block" and hookSpecificOutput.additionalContext; Claude receives equivalent current-turn context through its documented hook response.

  • Covers: US-003

• AC-010: Cursor and OpenCode receive the normalized diagnostic fields in their supported message or log shapes without an unsupported current-turn continuation claim.

  • Covers: US-003

• AC-011: Before hi update publishes candidate scaffold changes, it proves the candidate root is a marked, canonical descendant of the approved temporary parent and is neither an ancestor nor descendant of the live repository. Every candidate symlink resolves inside the candidate root. It then uses a fixed executable and argument allowlist, lifecycle scripts remain disabled, live manifests, lockfiles, dependency roots, and source stay unchanged, and the Effect patch runs only when selected.

  • Covers: US-004

• AC-012: Candidate lint findings are reported as adoption warnings, while dependency, process, configuration-load, malformed-output, or cleanup-proof failures block publication with actionable evidence.

  • Covers: US-004

• AC-013: Operator documentation gives bounded-target forms for bunx ultracite check <targets>, bunx ultracite doctor, bunx ultracite fix <targets>, and bunx ultracite fix --codex <targets>, and warns that omitting targets from check or fix defaults the operation to the current project.

  • Covers: US-005

• AC-014: ultracite fix --codex is an explicit operator action that starts a separate Codex CLI process; no managed post-edit hook invokes it.

  • Covers: US-005

• AC-015: Default Harness context packs do not install or copy Ultracite's AI rules, reusable skill, or generated provider hooks.

  • Covers: US-003, US-005

Constraints

• Automatic mutation is limited to Oxfmt and safe Oxlint --fix on the exact edited file. --unsafe and --fix-dangerously are forbidden in this path.
• The realtime hook uses direct Oxfmt and Oxlint processes. This preserves the existing staged, race-safe publication boundary and gives Harness raw JSON.
• Oxlint runs from the owning workspace and uses nearest-config discovery; the hook must not force a root configuration.
• Ultracite commands are deliberate operator workflows. They do not replace the normalized provider-neutral hook result.
• Existing project-owned rules, settings, and dependencies remain untouched unless they are an explicitly receipt-owned generated output in this spec.
• Every candidate-preview exit path must prove disposal of its isolated path.
• Project-local Codex hooks can still require manual trust after their exact definition changes; Harness must document that platform boundary.

Dependency Readiness

Ready. The linked research report records a disposable live probe of the exact six-package tuple, a successful lint-only Effect patch, Ultracite and Effect preset loading, and a structured effecttsgo(floating-effect) diagnostic. Upstream Ultracite tag ultracite@7.10.7 is immutable. Oxlint 1.81.0 is excluded because @effect/tsgo@0.39.0 rejects it.

Branch/Base Intent

• Parent/base commit: 694420ca15c8b37536338e85719c6ec00a7154df.
• Child branch: team/stefan/fix/ultracite-lint-config.
• The delivery remains on that child branch until normal review and merge; it must not be implemented directly on the default branch.

Accepted Technical Decisions

• Keep apps/cli/src/data/hooks/format-edited-file.mjs as the canonical runtime and generate provider projections from that neutral source.
• Reuse Ultracite's bounded repair protocol, not its prompt or context assets.
• Use direct Oxfmt/Oxlint for automatic edits and structured verification.
• Offer Ultracite check, doctor, fix, and fix --codex as explicit, bounded operator commands.
• Keep one normalized diagnostic/result contract. Provider adapters only translate that result into provider-native responses.
• Preview candidate lint state before update reconciliation and publication.

Accepted Testing Decisions

• Test behavior through the real hook process modes and public scaffold/update commands, not private parsing helpers alone.
• Capture RED before production changes for generated policy, hook results, provider responses, and adoption preview behavior.
• Add a live Codex fixture in create, validate, remove order. The fixture is not complete until the created hook is trusted, invoked after an edit, its continuation payload is observed, and every fixture artifact is removed.
• Prove the exact package tuple in a disposable dependency fixture with frozen resolution and an actual type-aware Effect diagnostic.
• Validate the four bounded Ultracite command forms against pinned 7.10.7 help or source before publishing the runbook.

Verification Seams

• Hook seam: process-mode input and normalized post-edit result.
• Provider seam: generated Codex, Claude, Cursor, and OpenCode response payloads.
• Scaffold seam: generated lint configuration, package scripts, and dependency declarations as consumed by a fixture repository.
• Update seam: candidate materialization, preview result, publication gate, and cleanup proof exposed through hi update.
• Operator seam: runnable, bounded Ultracite commands and documented scope.

Parked Decisions

• Approval-free project-local Codex hook execution is parked. Owner: Codex integration maintainers. Resume when Codex exposes a supported managed-trust mechanism; manual trust remains documented until then.
• Native current-turn continuation for Cursor or OpenCode is parked. Owner: provider-adapter maintainers. Resume when either provider documents a response contract equivalent to Codex or Claude.

Decision Log