Issue 203 implementation plan

Status: Complete.

Authority and decisions

Source: SPEC.md, https://github.com/wearedevpunks/harness-intelligence/issues/203.

architecture_applicability: local: repair existing scaffold/check ownership and producer behavior; add presence-only validity to the shared obligation schema for empty placeholders, without a new domain, dependency direction, or producer authority.
Dependency Readiness: User accepted the shared release base for issues #203–#207 on 2026-09-15.
Branch/Base Intent: Working branch fix/issue-203-scaffold-convergence; PR #208 targets team/stefan/release-issues-203-207, created from origin/main at 4b205afc5c8d707cb1c1918dd4574d4b41ba8471. Keep this branch and PR identity throughout closeout.
User supplied the complete defect boundary and acceptance behavior. Grilling frontier is empty; no requirements interview or speculative enhancement.
Planning inputs: grilling, parallel-research, swarm-planner, tdd, codebase-design, show-me. Two readonly lanes inspect wiki ownership and lint convergence; Main owns all integration and validation.
Plan language gate: repair producers; preserve authored wiki content; enforce managed integrity. No unresolved product terms or decisions.
Backlog sync skipped: supplied GitHub bug has no retained provider-task projection; configured backlog is Linear. This repair does not invent provider hierarchy or migrate the supplied issue. Uniform planning-only identities apply below.
Initial tracked tree clean; unrelated untracked .devpunks/delivery/v43/** evidence is not ours.

Findings and solution boundary

Scaffold's wiki staging preserves existing files, skips populated project/spec placeholders, and skips nested routes behind flat pages. wikiSemanticState currently compares unconditional starter files. Express starter ownership with the existing artifact obligation contract; preserve required file-type/presence checks and exact managed scripts/structured entries. Do not accept arbitrary observed bytes as managed desired output.

Lint rule application currently resolves namespaces using each asset's plugin list, even for transition rules whose plugin is declared by another selected asset. Lint read-only planning ignores JSON configuration that materialization merges. The generated handoff also reuses prior receipt-verified bytes after authoring completion, retaining stale pending actions. Fix these source decisions, not receipt hashes.

Task graph and execution

T1 wiki ownership -> T2 lint producer convergence -> T3 generated freshness -> T4 final proof/review

Serial execution: shared scaffold/update integration and regression fixtures; one integration owner avoids overlapping mutations. Research alone runs concurrently. Every code task proceeds through one public-result RED/GREEN cycle before the next.

Common task contract

Every task uses task_identity_mode: planning-only, backlog_item_id: not_applicable, backlog_item_url: not_applicable, relation_mode: unprojected, and backlog_sync_skip_reason: No retained provider-task projection; standalone GitHub bug repair.

Task status, edited files, RED/GREEN evidence, runtime results, and review outcomes are retained in IMPLEMENTATION-NOTES.md. review_mode: cli throughout.

Implementation skills: quality-types (reuse existing unions and inferred interfaces), codebase-design (test through scaffold/update public interfaces), tdd (public-result RED before behavioral edits), simplify (remove obsolete producer branches after proof), effect where existing Effect contracts are changed (preserve typed failures and dependency layers). Main runs validation once edits are stable; readonly lanes do not validate.

T1: Wiki starter ownership

status: Completed; preservation, healthy obligations, and strict negative controls verified.
evidence: Implementation notes.
depends_on: []
wave_boundary: W1
location / owned_paths: apps/cli/src/update/run.ts, apps/cli/src/update/run.test.ts, apps/cli/src/scaffold/stage.ts, packages/scaffold/src/baseline/obligation.ts, and the scaffold-state obligation helper.
description: Honor preserve-existing, populated-directory, and flat-route semantics. Keep required scripts and structured package obligations strict.
assigned_skills: quality-types, codebase-design, tdd, simplify.
implementation_skill_guidance: common contract above.
tdd_status: required
tdd_target: Customized existing wiki survives update/check; empty runtime starters remain valid; deliberately omitted seeds stay optional only behind nonempty flat pages or directories with non-hidden entries; genuine managed script damage remains actionable.
red_command / green_command: bun run --cwd apps/cli test src/update/run.test.ts -t "preserves authored wiki files".
expected_red_failure: False starter drift or missing deliberately skipped artifacts.
reason_not_testable: not_applicable; public-interface regressions and executable proof recorded.
validation: AC-001, AC-002, AC-003; add missing/type/managed-drift control assertions.
codebase_design_notes: runUpdate and scaffold materialization are the public seams; obligations own comparison semantics, not current hashes.
runtime_validation: required
runtime_target: Isolated repository scaffold/update/check.
runtime_evidence: Before/after change lists and preserved file bytes.
runtime_cleanup: Remove only unique temporary fixture directories after proof.

T2: Lint producer convergence

status: Completed; focused RED/GREEN and real lint loading recorded.
evidence: Implementation notes.
depends_on: [T1]
wave_boundary: W2
location / owned_paths: apps/cli/src/scaffold/output.ts, apps/cli/src/scaffold/output-wiki-plugin-alias.test.ts, apps/cli/src/scaffold/output-root-materialization.test.ts.
description: Resolve transition rule namespaces across selected plugin declarations; use equivalent JSON lint inputs in planning and materialization.
assigned_skills: quality-types, codebase-design, tdd, simplify.
implementation_skill_guidance: common contract above.
tdd_status: required
tdd_target: Existing JSON lint policy remains in emitted root config and subsequent desired output; package-targeted nested lint configs load without missing plugin errors.
red_command / green_command: bun run --cwd apps/cli test src/scaffold/output-wiki-plugin-alias.test.ts src/scaffold/output-root-materialization.test.ts.
expected_red_failure: Bare transition namespace fails lint loading or planned root differs from emitted root.
reason_not_testable: not_applicable; planning parity and real Oxlint loading exercised.
validation: AC-004, AC-005; real Oxlint loading and stable root/nested output.
codebase_design_notes: Existing output planner is the sole producer seam; no extra config parser or observed-byte acceptance.
runtime_validation: required
runtime_target: Generated configs loaded by installed Oxlint.
runtime_evidence: Exit status and decoded diagnostics; planning/materialization parity.
runtime_cleanup: Remove isolated repositories and retain command evidence only.

T3: Generated freshness after post-command work

status: Completed; ordinary update and repeated executable checks recorded.
evidence: Implementation notes.
depends_on: [T2]
wave_boundary: W3
location / owned_paths: apps/cli/src/scaffold/output.ts, apps/cli/src/scaffold/output.test.ts, apps/cli/src/update/run.test.ts.
description: Regenerate handoff from current authoring evidence and refresh selection through normal update without byte-acceptance shortcuts.
assigned_skills: quality-types, codebase-design, tdd, simplify.
implementation_skill_guidance: common contract above.
tdd_status: required
tdd_target: Completed authoring removes pending actions through normal update and reaches stable subsequent check.
red_command / green_command: bun run --cwd apps/cli test src/scaffold/output.test.ts src/update/run.test.ts.
expected_red_failure: Receipt-matching generated handoff retains obsolete pending actions.
reason_not_testable: not_applicable; current handoff generation and update convergence exercised.
validation: AC-006 and exact-managed drift control.
codebase_design_notes: Current authoring evidence is producer input; prior receipts classify writes rather than freeze stale output.
runtime_validation: required
runtime_target: Normal update followed by repeated check.
runtime_evidence: Fresh generated records and stable change lists.
runtime_cleanup: Temporary repositories only.

T4: Integrated proof and review

status: Completed for scoped proof; unrelated repository-wide gates remain blocked as recorded in implementation notes.
evidence: Implementation notes.
depends_on: [T3]
wave_boundary: W4
location / owned_paths: delivery evidence and touched regression files; subsequent docs/changelog cleanup scoped after smoke proof.
description: Exercise actual CLI commands on an isolated repository, run focused suites/types/lint once, and review against AC-001 through AC-006.
assigned_skills: review, verify-behavior.
implementation_skill_guidance: retain exact exercised results; no claim from mocks or unrun commands.
tdd_status: not_applicable
reason_not_testable: Verification task; behavior regressions belong to T1-T3.
tdd_target / red_command / expected_red_failure: not_applicable
green_command: focused CLI tests, package typecheck, scoped formatter/linter, isolated command smoke.
validation: All acceptance criteria plus no weakening of missing/type/managed integrity checks.
codebase_design_notes: Existing public commands and producer seams.
runtime_validation: required
runtime_target: Packaged CLI scaffold/update/check in an isolated repository.
runtime_evidence: Command output retained in issue delivery evidence.
runtime_cleanup: Unique owned fixtures only, after evidence capture.

Risks and final gates

Do not broaden repository ownership to generated scripts or all wiki paths indiscriminately.
Missing required regular files and symlink escapes remain failures.
Preserve project-owned package entries while enforcing managed structured keys.
A current selection may legitimately change after input consolidation; prove convergence after normal regeneration.
No project-wide validation while any writing worker is active. Final review uses frozen changes.
Docs: update existing docs/README.md, docs/runbooks/hi-cli-scaffolding.md, and changelog after runtime proof. No release or live checkout update.
Unresolved questions: none; concrete source or verification failures remain local implementation work unless accepted scope must change.

2026-09-15 closeout

User authorized committing, pushing, and creating the PR before resuming; PR #208 now exists on the accepted shared base. Publication of npm or baseline artifacts is not implied.
Review identified incomplete release intent and untracked, session-linked evidence. Retain the issue-203 summaries in .devpunks/delivery/issue-203/, explicitly distinguish unavailable raw captures from retained results, and provide runnable review commands.
Registry readback (npm view @punks/cli version --json) returned 5.0.1; prepare 5.0.2 with matching reviewed npm notes and baseline compatibility >=5.0.2 <5.1.0.
Release classification ran against committed closeout 51729a4e and the accepted shared base with a repository-local TMPDIR: mixed release, npm and baseline selected, classificationError: null, exit 0.
Resume-review regression strengthening passed four output/handoff cases and two update lifecycle cases; CLI type checking, formatting, JSON parsing, and diff checks passed. Fresh results are retained in .devpunks/delivery/issue-203/closeout.json.

Issue 203 implementation plan

On this page