Issue 224 Managed Lint Scope and Policy Grill Status

Scope and authority

Compose the accepted discovery/scope and Oxlint-authority research into one requirements record. Fix issue 224 across generated JavaScript/TypeScript lint, Lefthook, edited-file feedback, and update validation. Continue draft #225 on top of #223. Product implementation, consumer mutation, and release publication are outside this requirements task.

The user approved all presented proposals and expressly delegated routine defaults. The compiled record and lifecycle defaults are now explicitly approved; R2 closes the grill and authorizes full delivery.

• Decision log: Q1–Q24 is detailed authority.
• Scope research.
• Policy research and runtime witness.
• Existing Commit Gate language and update language remain applicable; superseded behavior is identified below.

Current Round

• Round: R2 — compiled record approved and grill closed.
• Current decision frontier: empty.
• Shared-understanding confirmation: confirmed by the R2 full-delivery instruction.
• Previously presented proposals: explicitly accepted by the user.
• Default authority: user authorized defining routine behaviors without needless questions; the log marks each such choice.
• Domain-modeling consistency: complete; glossary is now published in the canonical domain projection.
• No unanswered product decision or unknown active technical branch.
• Branch completion: 100%. Compiled-record approval is explicit; this is requirements closure, not implementation progress.

Branch dashboard

Compiled shared understanding

Selection and file ownership — Q2–Q7

The operating agent compiles the real Software Scopes and persists them:

{
  "lint": {
    "scopes": ["apps/web", "app/backend/core", "packages/ui"],
    "exclude": ["apps/web/test/fixtures/**"]
  }
}

lint.scopes contains exact repository-relative package roots, not glob subscriptions. Conventional apps/* / packages/* and declared workspace packages supply candidates, including nonstandard layouts. The saved list is authoritative. Each root must be contained, have its own manifest, and satisfy the supported tool/installation contract.

Wiki roots wiki, app/wiki, and apps/wiki are excluded. The agent records other embedded examples/fixtures in lint.exclude; explicit exclusions take precedence. Nested unselected package boundaries do not become parent source. Ordinary test files remain included. General repository discovery is retained for features outside lint.

Each eligible file resolves to one most-specific selected owner. A monorepo root normally dispatches; "." may explicitly own standalone/root application code, excluding child package boundaries and more-specific owners.

Lifecycle defaults — Q3, Q6–Q7

• Missing scope settings require explicit scope authoring. The agent can complete routine classification under the current task; the bare CLI reports the missing prerequisite rather than guessing from recursive discovery.
• An explicit empty list deliberately selects no software lint. It is distinct from missing/legacy settings.
• hi check reports selection/routing health read-only. Existing init/ensure and scaffold/update settings/handoff paths carry selection and preserve it.
• New ordinary files inside selected owners are covered. New application roots require a deliberate selection update; moved/missing roots cause actionable drift. --yes does not enroll every discovered package.
• Dependent new lint adoption waits for valid selection and compatible policy. Existing independent progress and recovery reporting remain truthful.

One effective policy — Q8–Q12

Every selected owner gets a canonical oxlint.config.ts. It explicitly composes only locally evidenced framework assets and preserved Project Lint Policy. React email code does not imply Next/TanStack; generic quality guidance does not imply Vitest.

Project policy lives in a separate project-owned input: oxlint.project.json is the default new filename. Existing compatible shared JSON/JSONC can remain explicit inputs. Migration inventories the effective parent/renamed/transitive policy chain and preserves explicit rules, ignores, overrides, environments, globals, settings, and path semantics. Opaque policy creates a named conflict.

Every managed entrypoint uses the same derived Lint Route and explicit config. The root command dispatches to owners. No second broad root lint pass or hand-maintained route registry is introduced.

Gates, migration, and recovery — Q13–Q19

Scope/exclusions are applied before staged routing and coverage. Excluded-only changes invoke neither managed linter nor formatter. Mixed changes check their eligible portion; renames/deletions select the right affected owner safely. Changes to shared policy, scope settings, routing, or relevant toolchain inputs select dependent owners for validation without treating root metadata as another implicit software scope or scanning excluded source.

Keep generated warning rejection, represented custom failure thresholds, read-only precommit formatting, disabled gate policy, and hook-manager coexistence. Edited-file mutation retains existing file-safety boundaries.

Compatible custom commands remain after verification. Incompatible commands stay intact with precise unresolved migration; the CLI must not report converged adoption while a known route still selects another policy. An arbitrary ad hoc user command is outside the managed guarantee.

Validate the whole proposed adoption before coherent activation. Configuration, tool, input, or authority failures block dependent activation. Lint findings retain existing preview/report behavior and do not authorize bulk application fixes. Retire only safely owned obsolete artifacts; preserve modified/unowned policy and never recreate excluded wiki/fixture output on the next update.

Inspectability and proof cover the actual owner/config/toolchain, transitive inputs, saved selection, and route. Reuse existing exact-input caching and read-only check semantics; no new service or whole-repository lint on every drift check is required.

Concrete scenario matrix

Technical grounding

E1–E4 are defined in the decision log.

The technical defaults name contracts and invariants, not implementation task order or new generic abstractions. Exact internal modules and reversible tactics belong to create-plan.

Glossary

Terms

• Software Scope: a selected package-root owner of software subject to managed quality checks. Avoid using “discovered package” or “workspace” as if either alone proves accepted ownership.
• Excluded Path: repository content omitted from managed quality execution regardless of surrounding owner.
• Project Lint Policy: project-authored rules and configuration choices preserved as inputs across baseline updates.
• Effective Lint Policy: the composed rules, settings, exclusions, and failure semantics applied to one Software Scope under the supported toolchain.
• Lint Route: the derived binding from a Software Scope to its executable config and command context.
• Lint Adoption: the validated, ownership-safe transition from prior lint setup to selected scopes and coherent routes.

Use the existing meanings of Commit Gate, Quality Command Contract, Scaffold Manifest, Validation Candidate, and Validation Result.

Relationships and axioms

1. A selected Software Scope has one authoritative Effective Lint Policy.
2. An eligible source file has exactly one selected owner; Excluded Paths have none for managed quality execution.
3. Settings records scope intent. Project Lint Policy records project choices. Lint Routes and canonical configs are derived outputs, not competing intent.
4. Equivalent managed verification selects the same policy, toolchain, file set, and failure semantics.
5. Ordinary tests are software; fixture/example projects are not implicitly software owners.
6. Discovery, ignored status, a baseline version, and cached proof do not establish current ownership or completed Lint Adoption.
7. Preserving arbitrary custom execution is compatible with parity only after verification or explicit unresolved adoption.
8. Findings, operational failures, and unresolved authority are distinct outcomes.

Resolved ambiguities

• “One layer deep” bounds conventional candidate discovery; selected declared custom layouts remain supported. It does not bound source-file depth.
• “Tests” means ordinary test source, which stays linted. Embedded test/example repositories and fixture content are separate exclusions.
• “One config” means one executable authority per owner, not one giant root file.
• “Preserve policy” includes inherited explicit choices and path meaning, not just retaining the bytes of a nearby JSON file.
• “Warnings” means severity; failure thresholds are separate and are preserved.
• “All entrypoints” means managed/adopted routes, not arbitrary future commands a user can manually invoke with a different --config.

Reconciliation and inherited constraints

Both research reports point here as the accepted decision record while retaining dated observations/candidate history. No executable implementation plan already exists for issue 224; create-spec and create-plan must reconcile these predecessor contracts without editing historic proof into a false new result.

Parked and out-of-scope work

No product branch is parked or deferred. Deliberate boundaries: bulk fixing consumer source findings, rewriting arbitrary shell automatically, global non-lint discovery redesign, a new remote service, unrelated Python/tooling redesign, publishing releases, and repairing this stack's inherited hook failures.

Non-design validation still required

• Full supported consumer reproduction and Mac/complete CI evidence.
• Settings authoring/read/write/upgrade behavior and realistic root/custom layouts.
• Correct local asset selection, inherited-policy semantics and command parity.
• Wiki/fixture exclusion, ordinary tests, staged rename/delete and deduplication.
• Coherent adoption, interruption/retry, ownership preservation and repeated convergence.
• Relevant-input cache invalidation and truthful conflict/drift feedback.
• Owning type/content/projection checks and real generated-runtime execution.

The observed 0-versus-25-error witness proves the existing defect, not a repaired implementation.

Handoff and work log

• Owning surfaces for authored artifacts: private wiki grilling/research and docs/README.md index; no product source changed.
• Skills: requirements-grill, grilling, domain-modeling, prior brainstorm, wait-what for plain decision wording, show-me for the view below, and writing-for-agents for durable handoff structure.
• HI-WIKI-001: pass — existing grilling route, both pages registered in metadata, content check passed.
• HI-WIKI-003: pass — frontmatter, evidence links, wiki-log bookkeeping, content check and all 3 public wiki contract tests passed. Local links and all 24 stable question IDs/answered states were checked.
• HI-DOCS-001: pass — product decisions live in the private wiki and the docs index routes to them; implemented runbooks remain truthful.
• CLI/shared-skill/runtime checks: not-applicable to this documentation-only diff; no implementation or generated runtime was changed.
• No changelog changed: release classification is none.
• Known publication limits: initial #225 draft used a one-time authorized hook bypass; existing broad wiki lint and pre-push argument failures remain outside this requirements task. This composition is local and does not reuse that exception.

All branches are now 100% closed. The glossary projection and compiled SPEC are written; implementation and remote retention proceed under full delivery.

Derived reasoning view

agent inventories and selects real software
                    |
        settings: scopes + exclusions
                    |
 local framework evidence + project-owned policy
                    |
       effective config + derived lint route
          /         |          |          \
      scripts       CI      Lefthook     edit hook
                    |
      same policy / eligible source / toolchain
                    |
       validated adoption and truthful health

This view summarizes Q1–Q24; the log and glossary are authoritative.

R2 — Explicit closure and delivery authority

On 2026-09-22 the user confirmed this compiled record: “i approve this. compose it into a delivery-phase and implement it. go finish it”. All eight branches are 100% closed, with no parked branches. Final domain consistency preserves the six terms and the existing Commit Gate/update vocabulary without contradiction.

• Canonical glossary.
• Compiled specification.
• Implementation proof and release readiness remain delivery work; closure does not assert them.