Scaffold and check convergence

Issue 224 supersession

The approved managed lint spec refines OUT-002 and AC-004–006: generated lint must converge for explicitly selected Software Scopes, with one effective config and route per owner. Root is an owner only when . is selected; otherwise it dispatches. Wiki and embedded projects are outside managed lint/format, and later reconciliation must not recreate their retired Harness lint assets. Ordinary application tests remain eligible.

The ownership and integrity obligations in OUT-001/OUT-003 remain. Compatible project-authored JSON/JSONC policy stays at its original path as an explicit input; oxlint.project.json is the new-policy convention. Only receipt-owned, unmodified obsolete assets may retire after policy preservation is verified. Modified/unowned files and incompatible custom commands survive with named conflicts. A receipt or matching baseline pin alone cannot establish live route correctness.

The earlier root/wiki namespace proof, drift counts, branch evidence, and implemented status below describe issue 203. They do not prove issue 224's T6 adoption/health or T7 parity; those gates own the new behavior's final evidence.

Context

Repository maintainers running hi scaffold against an established wiki receive starter-template drift for preserved repository content and missing findings for deliberately skipped seeds. Issue #203 records 27 drifted and 3 missing artifacts before post-command work, then 40 drifted and 3 missing after required authoring and lint correction. These observations are accepted evidence, not counts that every fixture must reproduce.

Non-Goals

No arbitrary-byte acceptance command, global drift suppression, wiki redesign, automatic repair of unrelated authoring, dependency upgrade, or release publication.

Requirements and Outcomes

OUT-001: Repository-owned wiki content survives lifecycle reconciliation

Scaffold, check, and update must agree about preserve-existing wiki files, populated directories, and flat routes. Validate repository-owned wiki artifacts according to their structural or semantic obligations rather than comparing them with starter-template bytes. Keep managed producers and direct repository mirrors subject to their actual integrity contracts.

OUT-002: Scaffold emits loadable, convergent lint configuration

Generated lint configurations must register the namespaces they reference. Root lint planning must converge with the state scaffold materializes.

OUT-003: Normal update converges after required post-command work

Required authoring and approved lint consolidation may stale generated handoff and selection records. A normal update must regenerate these records, preserve repository-owned content, and reach a stable subsequent check.

Acceptance Criteria

• AC-001: Customized wiki runtime, content, and bookkeeping files survive scaffold and update without starter-byte drift. Covers: OUT-001.
• AC-002: Populated directories and flat routes do not produce missing findings for intentionally skipped placeholders or nested starter routes. Covers: OUT-001.
• AC-003: Missing required artifacts, invalid artifact types, stale producer outputs, and genuine exact-managed edits remain detectable. Covers: OUT-001, OUT-003.
• AC-004: Generated root and nested Oxlint configs load without unresolved obsolete anti-slop/* rules. Covers: OUT-002.
• AC-005: A pristine scaffold-produced root lint config is current on the next check. Covers: OUT-002.
• AC-006: Normal update refreshes stale handoff and lint-selection output after required post-command changes; repeated checks and updates remain stable. Covers: OUT-003.

Constraints

Preserve confined filesystem and symlink safety. Receipt hashes record previous materialization, not permission to accept arbitrary managed bytes. Do not model hand-authored wiki runtime files as direct producer mirrors.

Dependency Readiness

Issue #203 is the first implementation PR above the shared release branch for issues #203–#207. The common branch is based on origin/main; each issue keeps its own branch in the GitHub-native stack.

Branch/Base Intent

Accepted by the user on 2026-09-15: preserve the working branch fix/issue-203-scaffold-convergence and use team/stefan/release-issues-203-207 as its PR base. The common branch was created at 4b205afc5c8d707cb1c1918dd4574d4b41ba8471 from origin/main. PR #208 retains that head and base. Release metadata and portable evidence closeout are in scope; npm/baseline publication remains outside this implementation task.

Accepted Technical Decisions

Use the existing ownership, obligation, and producer vocabulary. Correct producer behavior and ownership classification rather than weakening global drift checks. Preserve the semantic checks for customized wiki content.

Zero-byte directory placeholders use presence-only validity within the existing obligation model. Authored pages remain nonempty; runtime artifacts retain their required presence and file-type checks.

Accepted Testing Decisions

Keep focused public-interface regression coverage for these plausible failures. Exercise the actual scaffold/update/check lifecycle and lint loading in isolated repositories; do not mutate the operator's working tree to produce proof.

Verification Seams

hi scaffold, hi update, hi check --json, their existing public application interfaces, emitted Oxlint configuration loading, and filesystem contents before and after reconciliation.

Decision Log