Issue 203 implementation notes

Execution state

Core implementation and historical scoped verification are complete. Forty focused cases passed across split runs; four unrelated Commit Gate failures reproduced against original HEAD source and tests. Executable convergence and negative controls passed at the managed-artifact boundary. The original final Standards and Spec reviews reported no remaining findings; the 2026-09-15 resume review subsequently identified regression-strength and evidence/release closeout findings. No repository-wide clean-gate result is claimed.

The user authorized commit/push and the shared release stack on 2026-09-15. PR #208 uses head fix/issue-203-scaffold-convergence and base team/stefan/release-issues-203-207. The initial implementation commit is 7357f43b686f4866e45925f875e458e8c29ef6f3. No npm or baseline publication is claimed. The earlier retention attempt was blocked by wiki lint; the user subsequently authorized gate bypass for commit/push. This authorization does not establish a clean-gate result or weaken repository hook configuration.

Implementation

• T1: wikiSemanticState assigns repository-owned obligations to the finite preserve-existing starter set. Existing regular files remain authored; missing required files and unsafe types remain failures. Populated directories and flat routes satisfy optional placeholders/seeds. Raw-directory staging now uses the same populated-directory guard as other placeholder roots.
• T2: Lint rule aliases resolve against all selected asset plugins, including package-targeted transition assets. Planning and materialization both read existing JSON policy through readExistingJsonOxlintConfig.
• T3: Handoff generation always consumes current verified authoring proofs. Old receipt-matching handoff bytes no longer freeze obsolete pending actions. Normal update refreshes handoff, selection, and changed root lint output.
• Review repair: Zero-byte .gitkeep files use presence validity in the shared ArtifactObligation schema. Optional presence alone was insufficient because health validation also rejected present empty files. Required authored sections still reject empty content.
• PR comment repair: Flat Markdown alternatives waive nested route seeds only when they contain non-whitespace authored content. Placeholder directories use the scaffold population predicate and therefore ignore hidden entries. Wiki starter Markdown keeps authored-content validation, while runtime/configuration starters use regular-file presence so intentionally empty artifacts remain healthy.

The ownership helper extraction separates receipt/provenance decisions from repository-content retention without changing the early safety and mirror checks. No observed-byte acceptance command, broad wiki exemption, new dependency, or producer execution inside check was added.

Evidence

Repository-retained historical summaries are listed in .devpunks/delivery/issue-203/README.md: executable convergence (verification.json), validation matrix (validation.json), real Oxlint loading (lint-loading.json), baseline comparison (baseline-comparison.json), and original review (review.json). These files preserve observed results, diagnostic excerpts, and available hashes. The original full command captures, frozen review patch, and temporary fixture were session-local and are unavailable; no session URI is offered as portable proof. The original review summary applies only to its historical target, not subsequent changes. Use the review commands below to reproduce the public regression coverage on a fresh checkout.

Overall CLI check status

The two final hi check --json --baseline bundled --input <fixture> commands exited 1 for independent executable checks: checkout CLI 5.0.0, npm latest 5.0.1, and no detected global package manager for the directly executed build. Their only operation issues were cli-manager-not-detected and settings-pin-drift; baseline drift was false. These checks were not suppressed or repinned. This is managed-artifact convergence proof, not a claim that the entire environment check exited successfully.

Automated validation

• bun run --cwd apps/cli check-types: passed after the final production changes.
• bun run --cwd apps/cli build: passed; packaged CLI and bundled baseline rebuilt.
• Scoped CLI Oxlint: exit 0, zero errors, 155 Effect migration advisories across the checked files.
• Scoped scaffold obligation-schema Oxlint: exit 0.
• Oxfmt applied to the nine changed TypeScript files.
• Handoff stale/tampered/missing regression: three cases passed in its focused GREEN run.
• Final wiki preservation/health/confinement regression: one passed, 52 unrelated cases skipped. The fixture accepts its TypeScript/frontend pack selection; healthy obligations cannot mask pack-adoption drift.
• The six-file broad batch timed out after 1800 seconds. Split output regressions: 21 passed and four Commit Gate failures; original HEAD source/tests reproduced the same four failures. Wiki planning/alignment: seven passed. The affected update family passed all 12 selected cases with the verified Chromium prerequisite (41 unrelated cases skipped). Final matrix: .devpunks/delivery/issue-203/validation.json.

A combined cross-workspace lint invocation encountered duplicate registration in the existing packages/scaffold/oxlint.config.ts; separate package-scoped lint invocations passed. Repository-wide wiki lint previously blocked the spec commit with 497 errors. Neither unrelated configuration nor the hook gate was weakened.

Debugging and test decisions

Public results supplied RED evidence: unresolved plugin loading; root JSON-policy mismatch; stale action identities; and checkFailed: true with no changed files for empty placeholders. The last failure was independently found by executable proof and Standards review. Regression health assertions now inspect checkFailed, not only the file diff.

The symlink control fails during confinement preflight, before a per-file change list exists. Its regression asserts the typed rejection rather than requiring a later local-edited entry. A repository-authored page outside the finite starter set is not made a required artifact merely to validate its content.

The focused fixture initially failed with packDrift: true while every artifact obligation was healthy. Its accepted pack selection now follows the existing wiki-fixture convention. No production pack-adoption gate or health assertion was relaxed.

Tests used a unique repository-local TMPDIR because /tmp was near inode exhaustion. The validation process used umask 022: inherited permissive mode otherwise produced projection byte-equality/mode-inequality failures. These settings affect the isolated verification environment, not production behavior.

The inherited test environment initially lacked AGENT_BROWSER_EXECUTABLE_PATH. Required-tool bootstrap attempted agent-browser install, adding a legitimate failure issue and making otherwise no-op updates report failure. Instrumentation confirmed the expected lint-preview blocking behavior was unchanged. Final update-family verification uses the installed Chromium executable, as the successful packaged smoke did; no bootstrap failure or assertion was suppressed.

The 2026-09-15 PR comment repair used three focused RED/GREEN cycles through the same public lifecycle regression. Before the production fixes, whitespace-only flat routes hid both nested seeds, a dotfile-only directory hid its missing .gitkeep, and an empty runtime stylesheet was rejected as authored content. The final exact-tree run passed with one focused test and 52 skipped tests; CLI type checking, scoped Oxfmt/Oxlint, and git diff --check also exited successfully. The regression retains an empty required Markdown page as a negative control.

The unrelated Commit Gate comparison is retained in .devpunks/delivery/issue-203/baseline-comparison.json against 4b205afc5c8d707cb1c1918dd4574d4b41ba8471. Temporary baseline source/test copies and diagnostic instrumentation were removed.

Skill and review evidence

quality-types: shared schema extension and existing ownership unions; LSP references checked before schema modification. codebase-design: existing planner and public update/check seams. tdd: observable RED/GREEN boundaries above. simplify: removed stale handoff reuse and consolidated lint-input reading. verify-behavior: packaged commands and real Oxlint loading. No React surface changed.

Epoch-1 Standards review found the empty-placeholder P1; Spec review found no scope mismatch. Final Standards review confirmed the P1 resolved and no new findings; final Spec review confirmed AC-001 through AC-006 remain represented. Reviewers ran no validation commands. The subsequent test-only symlink assertion correction follows the exercised preflight behavior; production code remained frozen.

Manual Review Checklist

Run from the repository root after bun install --frozen-lockfile. Use umask 022, create a unique repository-local temporary directory with mkdir -p .tmp && export TMPDIR="$(mktemp -d "$PWD/.tmp/issue-203-review-XXXXXX")", and set AGENT_BROWSER_EXECUTABLE_PATH to an installed Chromium executable before the update tests. These are isolated test fixtures; do not run scaffold/update against the operator's checkout to reproduce them.

Docs ingest

Private/internal ingest complete. Updated the existing scaffolding runbook and docs index, npm/baseline changelogs, routed spec index, and implementation evidence. The existing runbook owns the lifecycle flow and ownership contract; no duplicate flow/concept routes were introduced. The research report remains pre-repair source evidence. A compact projection-health memory note explains why zero changed files do not prove healthy obligations. Route synchronization passed; source ingest metadata and the capped wiki log were updated.

Task-owned validation directories, smoke fixtures, temporary baseline source/test copies, diagnostic instrumentation, and the umask wrapper were removed after proof retention. The supervised regression process exited successfully. Concise historical evidence remains in .devpunks/delivery/issue-203/; full original command captures are unavailable. Unrelated .devpunks/delivery/v43/ work was untouched.

Release closeout

The next Affected Verification RED reported TS2339 because ManagedFileSummary intentionally has no mode property. The repair resolves declared mode authority from expected.desiredState.files, validates only files with declared modes, and leaves undeclared projection modes untouched. The recovery regression passed under umask 002 and 022 while proving an undeclared handoff retained mode 0600; CLI typecheck, focused formatting, lint, and diff checks passed. Final CI remains pending the repaired head push.

The changed npm and baseline changelogs select a mixed release. Registry readback on 2026-09-15 returned npm 5.0.1, so the pending npm release version is 5.0.2, with matching dated notes; baseline notes retain nonempty reviewed changes and compatibility >=5.0.2 <5.1.0. Classification against committed closeout 51729a4e and team/stefan/release-issues-203-207 passed with classificationError: null and exit 0. Four focused output/handoff tests, two update lifecycle tests, CLI type checking, formatting, JSON parsing, and diff checks passed. The first PR affected-verification run exposed one unformatted changed test file; Oxfmt repaired indentation only and the next CI run advanced through formatting. That run then proved the new dynamic-import assertion could not resolve ultracite from a system-temporary fixture. The assertion now inspects the emitted policy directly, while the separate plugin-alias regression retains real loading coverage; the focused policy test passed with TMPDIR=/tmp. .devpunks/delivery/issue-203/closeout.json retains these results. Historical test evidence above still records the actual 5.0.0 executable used for those runs and is not rewritten as evidence for a new build. No npm or baseline publication is claimed.