Issue 224: Lint Scope and Hook Boundaries

The user subsequently accepted the proposals in this report and the follow-up policy report. The managed lint grill now records accepted decisions and delegated defaults. The observations and candidate/open-decision wording below retain the research-time history; they do not reopen choices settled in the grill. Compiled grill confirmation is pending.

Status and accepted bounds

Brainstorming evidence, not an accepted implementation specification. The user requested a new PR stacked on #223, coverage of #224, exclusion of destination wiki paths from linting and Lefthook, and lint/hook package discovery bounded to one child under apps and packages. Candidate solutions below remain pending acceptance. No production behavior changes in this research commit.

Accepted during the brainstorm: the same scope must apply to every managed lint entry point, including edited-file feedback, Lefthook, and generated lint commands. Explicitly declared workspace packages may also qualify beyond the conventional apps/* and packages/* layout; the rule is not a strict conventional-path-only allowlist. Ordinary tests inside eligible applications/packages remain linted. The excluded content is embedded example repositories, fixtures, and similar nested projects.

Research baseline: #223 head ecf2d68eb69f0bd2977baf13ced39f230bdccdea. The issue reports CLI 5.1.1 behavior in another repository; that consumer has not been reproduced here. The local release-preparation commit above #223 is not part of this stack.

The operator is an agent running hi scaffold, hi update, lint, edited-file feedback, and commits in a destination repository. apps/cli owns discovery, selection, generation, reconciliation, and the shipped runners. Shared scaffold contracts may be affected if the accepted design changes their shape. API and backoffice changes have no established need. CI is an execution consumer of the selected commands; rewriting destination workflows is an unresolved scope choice. The private wiki owns this research; docs remains implemented-operation authority.

Evidence and uncertainty

Two readonly lanes covered discovery/technology selection and generation/runtime hooks respectively. The coordinator examined issue/PR evidence, established the stack base, consulted existing lint learnings and the scaffolding runbook, and consolidated this report. No lane ran a consumer reproduction or modified code.

Candidate coherent system

One lint-specific eligibility decision should precede lint asset selection. Keep general repository discovery available for other consumers unless evidence shows that its wider topology is itself unwanted. Existing nested-workspace detector tests intentionally cover more than apps/* and packages/*.

destination manifests + source evidence + existing ownership
  -> lint eligibility: package root, exclusions, reason
    -> per-workspace technology evidence and lint assets
      -> explicit lint config and command routing
        -> scripts / Lefthook / edited-file feedback / update validation
          -> findings and exclusions reported against the same scope

This is a proposed relationship, not a new persisted schema. Reuse existing selection/contract artifacts where possible; a new independent registry would need justification.

User-proposed settings authority

The user subsequently proposed that the operating agent compile the actual software-facing scopes while running the CLI and persist the list in .devpunks/settings.json. The user accepted this architecture in the follow-up discussion, including preserving incompatible custom commands and reporting their routing conflict for deliberate migration. Exact field names remain proposed. The current ProjectSettingsDocument contains commit-gate policy and repository quality commands but no software/lint scope list (apps/cli/src/features/project-settings/model.ts:20–51).

Recommended interpretation: discovery proposes candidate owners; the agent classifies real software versus embedded example/fixture projects; settings stores the explicit selection; the CLI validates it and generates every managed lint entry point from it. Keep inferred technologies derived per scope rather than storing a second copy of framework detection in settings.

Illustrative settings shape only; field names are not accepted API:

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

This would make shallow conventional paths and declared workspaces inputs to initial scope selection rather than permanent competing runtime authorities. Saved paths should be repository-relative and validated; a moved/missing scope should yield actionable drift, not silently trigger recursive fallback. Adding a new fixture manifest must not silently grow the saved application list. Ordinary tests remain covered. Wiki stays excluded; nested fixture/example exclusions are still needed underneath selected owners.

Open consequences: who updates the list when real apps are added, migration for settings without the field, whether root . is permitted for standalone apps, and how exclusions are identified and persisted. An agent may author proposed settings, but hook correctness cannot depend on an agent running at commit time. Settings schema/service/initialization/update paths become additional implementation owners, and the new spec/plan must cover persistence, drift, and deterministic consumption as well as discovery depth.

The subsequent consumer policy investigation reproduces the reported entrypoint disagreement and proposes config-authority migration. Those additional migration details remain candidates.

Intake is manifest/source evidence, not repository-wide technology union alone. State is the selected owner/config/command and its provenance. Control is the existing scaffold/update and quality command contract. Feedback must distinguish an excluded path, an eligible owner with findings, and a routing/configuration failure. Recovery uses ownership-aware update reconciliation; a narrowed scope must not silently erase custom policy. Handoff should name remaining command or ownership conflicts and the smallest validation that can resolve them.

Open decisions

1. Accepted: explicitly declared nonstandard workspaces may qualify, including app/backend/core if declared. How broad workspace globs interact with excluded nested fixture projects remains unresolved.
2. Accepted: ordinary tests remain linted; embedded example repositories, fixtures, and similar projects are excluded. A blanket test/tests directory exclusion would contradict this decision.
3. Accepted: the same exclusions cover edited-file feedback, Lefthook, and all other managed lint entry points.
4. Is the root an orchestrator in monorepos, while a root-only application remains supported? Root policy inheritance is not evidence that the root is another app.
5. Does “wiki paths” mean the three established wiki roots and their descendants, or every directory segment named wiki?
6. How should existing custom root/owner commands be handled when their scanning scope or selected config contradicts the new generated policy?

The first three questions were presented to the user during research. The user accepted shared scope for every managed lint entry point, eligibility for explicitly declared workspace packages, and continued linting of ordinary tests while excluding embedded example/fixture projects. Other branches are explicit unknowns, not accepted defaults. A draft PR makes the evidence reviewable; it does not resolve #224.

Reconciliation required after acceptance

• Add the issue-specific accepted spec and execution plan; scope implementation workers by discovery/selection, generated runtime, ownership migration, and documentation only after shared contracts and dependencies are settled.
• docs/runbooks/hi-cli-scaffolding.md:259 explicitly describes wiki lint configs; its lint-feedback, workspace-validation, and commit-gate sections must reflect the accepted exclusions and command authority.
• docs/README.md currently describes wiki exclusion from pack detection, not linting. Keep current-behavior prose unchanged until implementation proves the replacement; this PR only links the research.
• Reconcile affected authority in the context-compilation, scaffold lint baseline, managed format hook, Lefthook commit gate, portable commit gate, and lint-feedback specs/plans. Mark superseded contracts explicitly rather than rewriting historic proof as though the new behavior already existed.
• Existing relevant artifacts are under apps/wiki/content/docs/project/specs/cli/: IP-317-compile-context-once-and-project-it-truthfully, scaffold-lint-config-baseline, scaffold-managed-format-hook, lefthook-commit-gate, issue-204-portable-commit-gates, and issue-181-lint-feedback-adoption.

Proposed behavioral proof

Use the public scaffold/materialization seam to cover an eligible frontend, an eligible backend, shared code, wiki, and nested fixture manifests. Assert exact owners and framework assets, not only snapshots of generated text. Existing seams include scaffold/output.test.ts, output-root-materialization.test.ts, detector and compiler tests, features/commit-gate/quality.test.ts, and generated runner and edited-file hook tests.

Run real representative commands to prove excluded files are never passed to managed tooling; cover excluded-only, mixed, delete, and cross-boundary rename staging. Prove script/hook config agreement and ownership-safe update convergence with unmodified managed, modified managed, and unowned old configuration. This is a proposed verification set, not evidence that implementation passes it.

Handoff work log and rule evaluation

• HI-WIKI-001: pass by using the existing project research route and registering the page in its owning metadata; authored content check passed.
• HI-WIKI-003: pass; frontmatter, source evidence, authored content check, and public wiki contract (3 tests) passed. This is authored research, not raw source ingestion, so processed-source bookkeeping is not applicable.
• HI-DOCS-001: pass; research is private wiki material and docs/README.md only indexes it. No claim of changed implemented behavior.
• HI-CLI-001, HI-CLI-003, HI-CLI-004: pass for readonly boundary inspection; implementation and generated-asset validation are not applicable to this diff.
• Shared contracts, reusable skills, infrastructure, local URLs, auth, and UI runtime rules are not applicable to the authored research diff.
• Baseline bun run --cwd apps/wiki check:content: passed before authoring.
• Authored content check and public wiki contract: passed after installing the frozen dependencies with lifecycle scripts disabled. The first test attempt could not load vitest/config before dependencies were installed.
• No changelog is changed; this research selects no product release under the repository's changed-changelog rule.
• Commit attempt blocked by the existing pre-commit gate: wiki lint reports 456 errors in unchanged source and bundled plugin files. The documentation-only diff does not fix or introduce those errors.
• Existing pre-push gate also fails before publication: it calls the Candidate Evidence CLI with unsupported --base / --head arguments; the observed error is Invalid Candidate Evidence argument: --base.
• The user explicitly authorized one-time pre-commit/pre-push bypass for this three-file documentation-only draft. Use per-command overrides; retain the repository hook configuration and both failures as unresolved evidence.