Implementation Notes: PR #88 Review Remediation

Summary

• Every accepted PR #88 implementation and review finding is repaired. T1-T10 and the accepted findings-first review are complete.
• Final aggregate CI parity is complete. Live PR/Linear authority remains pending under T14. These notes do not claim a final docs SHA or GitHub run result.

Execution Mode

• parallel
• Logical waves use all three available implementation-worker slots. Capacity batches preserve disjoint ownership and dependency barriers.

Deviations From the Plan

• T1 retained the pre-existing submitter seam only until the planned T9/T10 consumer convergence. It introduced no new compatibility alias.
• The first interruption fixture used fs.watch and hit EMFILE while the old blocking implementation held the event loop. The final deterministic fixture uses setImmediate file readiness without sleeps or open watchers.

Surprises and Decisions

• PR #88 is a single main-based core PR. The user explicitly prohibited stack dry-runs; no stack command belongs to this run.
• T9 integration tests caught two real cross-module regressions: duplicate matching had become exact-body-only, and DB resume used retry-request metadata in the issue draft. Both were repaired at their owning feature/adapter seams.
• Focused characterization initially treated report ID byte shape as internal. Runtime-product immutable bytes proved the 31-byte shape is externally observable, so T6 restored the historical stable ID construction and added a regression test.
• The missing-runner case belongs to production composition. It was removed from the T9 test facade and is required in T10.
• The first T10 runtime run caught double CORS and report-ID byte drift. Route-only CORS plus the stable ID repair restored immutable runtime output.
• The final settings correction combines the governed preflight with one atomic change instead of exposing partially updated calculated-tools and managed-version state.
• Skills CLI cleanup now targets the owned process tree on POSIX and Windows. Cleanup failure preserves its underlying cause, including interruption cleanup.
• The report feature converged on ReportSubmission.Service.submit as its sole use-case seam. Retry carries raw report identity, identity hashing is injected, interruption releases claims safely, and Drizzle retries only unfinished deliveries.
• The API entrypoint is now a 32-line process root over extracted feature, HTTP, runtime, provider, persistence, and artifact modules.
• CI exposed two final portability gaps. The safe wiki type-generation order now propagates into generated consumer scripts, and Skills process-tree cleanup is bounded under load.

Sanity Checks

UI Evidence Links

No UI surface changes. This remediation changes CLI/API behavior, architecture, process lifecycle, tests, and documentation only.

Runtime Validation Evidence

Acceptance Criteria Status

Manual Review Checklist

Pre-existing Issues

• None known inside the accepted scope.

Out of Scope Observations

• None.

Final Validation Authority

• Primary implementation commit: f1516f43e51c0c1e4baf4c931408ae8cc3d534d8
• CI follow-up head: aabefa39b1a3e63e258f38d4d0ac1af219ee8d2d
• Exact test:ci: base starting 402c7dcc, head aabefa39b1a3e63e258f38d4d0ac1af219ee8d2d; Effect aggregate 95 pass, 1 deliberate skip, 0 fail; behavior contracts 46/46; Turbo 30/30 in 55.392s
• Standalone: CLI 913/913; API 250/250; Effect 96/96; check 12/12; check-types 13/13; build 6/6; runtime product valid:true
• Generated wiki source digest: 6e8fdb01a0f8640a574d2abe36d5920d7fd7c3376854cae9568636971351fd03

Final PR Delta Evidence

Codex thread r3661760774 identified Linux clipboard subprocess environment leakage. The fix passes only the session variables required by Linux clipboard tools: DISPLAY, WAYLAND_DISPLAY, XAUTHORITY, and XDG_RUNTIME_DIR. Unrelated environment values, including secrets, are filtered.

Behavior-contract run 30315543025 attempt 1 failed during runtime-product db:migrate. The unchanged attempt 2, job 90141295639, passed, identifying a transient host-port readiness race rather than a source change. The runtime fixture now probes select 1 through the exact host DATABASE_URL before migration and redacts migration diagnostics.

Current local proof passes CLI config 11/11, the full CLI suite in 76 files with 913 tests, focused runtime product 1/1, and the full API suite 250/250. Standards and Spec delta reviews are clean. Structured autoreview could not run because the private-code egress gate blocked the review payload; this is recorded as a tooling blocker, not a clean structured-review result.

Four Final Codex P2 Repairs

Threads PRRT_kwDOR4a5Es6UPzsf, PRRT_kwDOR4a5Es6UPzsi, PRRT_kwDOR4a5Es6UPzsm, and PRRT_kwDOR4a5Es6UPzsr are implemented:

• Startup cache reads and background process spawns are advisory. RED proved a rejected cache/spawn path escaped startup handling and could abort a non-JSON command before its handler ran. The command now continues while JSON ownership remains unchanged.
• Windows mutation and migration recovery emits a cross-shell powershell.exe -EncodedCommand payload encoded as UTF-16LE. RED proved shell-sensitive cwd, agent, and token values could enter the recovery command unsafely. The encoded payload carries those values literally and emits no diagnostics.
• The memory report repository reuses only unfinished delivery. RED reused a completed identical report and collapsed a later occurrence; completed records, including an identical report with a new createdAt, now create a fresh occurrence.
• Skills CLI binding failures preserve every verified partial copy and its lifecycle status. RED discarded verified peers when binding inspection failed; the failure now carries partial evidence through operator status and mutation/migration recovery.

Focused proof passes CLI 72/72 and API 65/65. Worker full suites pass CLI 922/922 and API 252/252. Three Standards/Spec delta reviews are clean. Native Windows execution is the only residual validation item. Structured autoreview remains blocked by the private-code egress gate, so no structured clean result is claimed. No final commit SHA or live CI result is recorded.

Remaining Work

• T14: commit/push only when authorized by the parent workflow, then verify live PR head/base/checks/threads and tracker readback. PR #88 must remain open and unmerged.

Historical Evidence Boundary

PR #87 implementation SHAs, runs, stack topology, and test totals remain historical IP-320/IP-324 delivery evidence. They are preserved in their original artifacts and do not stand in for PR #88 final authority.

Steering

2026-07-28 Latest Codex Review Repairs

Threads PRRT_kwDOR4a5Es6UT9bT, PRRT_kwDOR4a5Es6UT9ba, and PRRT_kwDOR4a5Es6UT9bd are implemented locally:

• A valid local-only report response no longer requires githubUrl. The CLI records the accepted report and returns successful semantic facts keyed by reportId; URL-only review actions are omitted.
• Auth configuration startup failures remain BackofficePersistenceUnavailable at protected session boundaries. Anonymous recovery remains confined to optionalBackofficeOperator.
• Authoritative full and affected Turbo CI commands now run workspace check tasks alongside test, check-types, and build. Browser tests remain explicit, and affected mode still runs API runtime validation outside pruning.

Focused RED evidence reproduced the URL response failure, the misleading Unauthorized auth result, and missing check command entries. Focused GREEN proof passes CLI 10/10, API 9/9, behavior scope 4/4, and the public report/API guard 69/69. Final aggregate validation and live PR evidence remain pending.

A follow-up corrected the affected supplemental runtime-product graph by removing Turbo --only while retaining --filter=@punks/api without --affected. The real Turbo dry-run now includes @punks/api#test, and @punks/api#validate:runtime-product depends on that evidence producer. Browser and Playwright tasks remain absent. Focused behavior-contract proof passes 14/14.

Two baseline-integrity follow-ups are implemented locally. The API now validates the initial artifact URL and every redirect as absolute HTTP(S), follows at most 20 redirects manually for every source, and confines GitHub authorization to the initial asset API request. Invalid redirect evidence is an integrity failure; network and body transport plus declared HTTP 503 remain unavailable. Every other terminal status fails closed as an integrity failure.

The CLI now structurally decodes embedded baseline metadata through the shared scaffold schema before cache writes and reuse. Requested channel, resolved version, release provenance, canonical tag, and declared compatibility must agree with authority. Verified schema-v1 metadata may omit compatibility and informational fields; a present compatibility range must agree. Focused proof passes API 12/12, CLI 64/64, and scaffold schema/public contracts 13/13.

The CLI runtime configuration boundary now preserves empty presence markers without relaxing shared environment value decoding. Empty CI, VITEST, NO_COLOR, and FORCE_COLOR retain presence semantics; valued settings still treat empty as absent. The safe child-command environment includes BUN_INSTALL alongside PATH while excluding unrelated secrets. Focused config proof passes 14/14; the full CLI suite at that checkpoint passed 944/944, with CLI check and typecheck green.

Repository Git-config discovery now preflights repository identity before querying remotes. Preflight status 128 means no repository; remote-query status 1 means no matching remotes. Every other failure, including a corrupt repository config returning status 128 during the query, remains a typed ProjectSettingsAccessFailure. RED proved corrupt config could be collapsed into GitHub fallback inference. GREEN preserves non-repository, valid no-remote, and linked-worktree behavior. Focused project-settings proof passes 23/23; the full CLI suite passes 946/946, with CLI check and typecheck green.

The final remote P2 architecture keeps repository-wide validation at the root: test:ci invokes bun run check:repo directly before Effect and behavior-contract validation. The full and affected Turbo plans still run workspace check alongside tests, typechecks, and builds, while affected API runtime-product validation retains its test evidence producer. The scope runner therefore forwards Turbo dry-run output without a separate root-check command-plan or output-routing layer.

Project-detail reads are fully uncached. Every request crosses the public getProjectUsageDetail seam, so transient unavailable and transport failures can recover on the next call, and stable rejected not-found failures remain typed without serialization or cache eligibility. Focused root-suite and scope proof passes 13/13, focused backoffice client proof passes 11/11, and the full backoffice suite passes 76/76. The full behavior-contract suite passes 47/47; backoffice check and typecheck are green.

2026-07-28 Final Containment and Projection Contract Repairs

The receipt-path resolver now exposes an explicit followLeaf policy that defaults to true. Managed-file observation, receipt hashing and mode capture, file application, manifest prevalidation, and stale-file removal pass false because they act on the link itself. Structured entries and dependency manifests retain the default and therefore follow a leaf symlink when proving containment. Root aliases remain invalid, while managed dangling and external-target leaf symlinks preserve their link-local behavior.

The write-mode RED added an in-root structured-entry symlink to external JSON. It observed no invalid entry before the repair; GREEN records the typed failure and leaves the external sentinel unchanged. All 82 update shard cases pass; with the two-test shard partition contract, the focused update aggregate is 84/84.

HarnessProjectionUnsupported is accepted only for a capability declared degraded. It becomes a typed unsupported omission and partial projection. Returning the sentinel for a supported capability now produces InvalidHarnessProjectionError. Cursor's arbitrary lifecycle-hook omission remains valid, and its known hook mirrors remain unchanged. The active and bundled projection cores are byte-identical.

Exact proof passes the Cursor and projection contracts 41/41, baseline resolution and public context contracts 86/86, CLI typecheck, the canonical CLI build, and the installed-package surface assertion. The regenerated bundled baseline digest is 8d1b69287afc71638f4296da98072202f3e7ad04ed8f21e883eb941e7f857da4.

2026-07-28 Final Baseline and Isolation Contract Repairs

Tokenless public GitHub release archive URLs now use the direct download path without authorization. Configured-token flows retain GitHub asset API resolution, while authorization remains confined to the initial API request and is never forwarded across redirects.

Published baseline inventory accepts only sha256: digests with exactly 64 lowercase hexadecimal characters for both archive and manifest assets.

The root local and CI behavior entrypoints now both execute the repository isolation contract explicitly before the scope contract. Focused aggregate proof remains the acceptance gate for these repairs.

2026-07-28 Pinned Shared-Skills Sync and Provider Alignment

The shared skill source is fixed at ref team/stefan/write-backlog-milestones, commit 621547803e89c209f72764f6b5939803adfd95d1. The default Harness sync now fetches that ref and fails closed before checkout or bundle copy when fetched HEAD does not equal the pinned commit. A validated HI_SKILLS_REPOSITORY_REF remains an explicit intentional override, and sync metadata records both its requested ref and resolved commit.

The synced write-backlog guidance aligns provider-native execution milestones: GitHub uses dependency-derived chronological repository milestones while Project V2 tracks capability-module ownership; Azure DevOps uses Iteration Path for execution milestones, Area Path for module ownership, and paired dependency links; monday.com keeps groups as modules, uses a Status or Dropdown Execution milestone column, and limits dependency links to the same board.

The canonical bundled identity regenerated to e4594ac24f43975f69e9bfa6740616d6ef2de8f0f6af379a868660845277343c. A full hi update --check --baseline bundled --json preview contained unrelated managed drift and was not applied. The active copy was instead refreshed through the targeted Skills CLI local-source route after --list proved exactly one skill:

npx skills add ./apps/cli/skills/agnostic/requirements/write-backlog \
  --skill write-backlog --agent codex --copy --yes

The generated bundle and active skill trees are byte-identical. The non-portable skills-lock.json produced by the local absolute source was removed. RED reproduced three failures with six passing tests; GREEN passed the focused sync suite 9/9 and the combined sync plus bundled-identity suite 12/12, with CLI typecheck, check, build, and diff integrity green.

2026-07-28 CLI 3.0 Beta Projection and Failure Boundary Repairs

Four final CLI boundary repairs are implemented locally:

• Claude and Codex lifecycle adapters now return HarnessProjectionUnsupported for hook IDs without an explicit native configuration. Their two configured hooks retain mirror and configuration actions.
• OpenCode retains mirror and formatter configuration only for format-edited-file. scaffold-update-check and unknown hook IDs are typed omissions instead of mirror-only success.
• RepositoryCheckOperationFailure now maps at presentationOutcome to one structured expected-failure document in JSON mode. The typed tag, operation, and message are preserved; stdout contains exactly one JSON document, stderr stays empty, and the exit remains nonzero.
• Lifecycle-hook reconciliation observes the exact desired semantic value and removes at most one exact prior receipt occurrence. Consumer wrappers sharing the managed command retain their matcher, timeout, metadata, and relative order.

The bundled and active Claude, Codex, and OpenCode adapters are byte-identical. Direct managed-asset fixtures include the resulting adapter, handoff, and projection receipt hashes and omit the unsupported OpenCode update-check plugin. Focused proof passes projection 62/62, presenter and packaged JSON 2/2, and lifecycle update 2/2. The canonical build regenerated the final bundled baseline digest to ac7677379ccf061f00202c29d1af56846bf640afa792ad49e9fad03d41138d49.