Issue 204 portable commit gates implementation notes
Issue 204 portable commit gates implementation notes
Execution state
Implementation is complete and ready for delivery review. The former parent-PR guard passed when the user supplied PR #208. The child began at its original head 7357f43b686f4866e45925f875e458e8c29ef6f3, fast-forwarded to 2d8839978075419cb9a8a70f296f078626d31a7d, and was subsequently rebased through the moving stack to current parent head d50fe8b6a63cea52db6a2ff56e2c9b42868ef79d; PR #208 remains open with base team/stefan/release-issues-203-207.
Task evidence
active Git worktree root
+ repository-relative owner path
→ resolved owner cwd
→ lint and format-check commands
legacy contract root → accepted in input, ignored as execution authorityThe runner executable remains the sole behavior seam: Git discovery and launch-error capture stay internal, while failures expose the resolved owner cwd and underlying cause.
| Task | Status | Evidence |
|---|---|---|
| T1 portable runner and diagnostics | Complete | Recovered aggregate RED→GREEN plus two review-repair RED→GREEN cases; full runner suite passes 9/9, including linked-worktree, missing-owner, trailing-space, and trailing-carriage-return checkout paths. |
| T2 rootless generated-contract coverage | Complete | Materialized JSON is decoded once and proves relative Owner paths with no own root; focused and combined suites pass. |
| T3 synchronized operator documentation | Complete | The new Commit Gate paragraph is byte-aligned between root and routed runbooks; README points to the existing lifecycle seam; content sync and Fumadocs generation pass. |
Review repair 1 added a separate public-boundary RED→GREEN for a real checkout path ending in whitespace. Review repair 2 added a real repo\r RED→GREEN and hardened linked-worktree cleanup failure reporting. The full runner suite now passes 9/9 and the combined runner/output suite passes 28/28. The original seven-test GREEN remains only in PLAN.md as historical TDD chronology.
Validation
| Gate | Result |
|---|---|
bun run --cwd apps/cli test -- src/data/scripts/commit-gate-runner.test.ts src/scaffold/output.test.ts | Passed after repair 2: 2 files and 28/28 tests. |
bun run --cwd apps/cli check-types | Passed. |
bun run --cwd apps/cli lint | Passed with the inherited warning baseline and no errors. |
bun run --cwd apps/cli format | Repository baseline limitation: failed only on three unchanged parent files (scripts/classify-release-impact.mjs, scripts/staged-verification-selector.mjs, and src/cli/command-registry.ts). |
bunx oxfmt --check for all four changed CLI files | Passed. |
bun run --cwd apps/cli build | Passed after repair 2; deterministically regenerated bundled-baseline-identity.generated.ts to digest 23ddfddfc140e560f076d57c4f98b20ab0368aeea03861a447c16b4fb869de99 for 825 assets. |
bun run --cwd apps/wiki check:content | Passed. |
bun run --cwd apps/wiki postinstall | Passed; Fumadocs MDX generated successfully. |
git diff --check | Passed. |
The post-rebase package-format rerun reports three unchanged parent files: scripts/classify-release-impact.mjs, scripts/staged-verification-selector.mjs, and src/cli/command-registry.ts. Every #204-touched file passes focused formatting.
Acceptance Audit
| Criterion | Status | Evidence |
|---|---|---|
| AC-001 | Met | Stale absolute Legacy root regression executes from the Active Git worktree root. |
| AC-002 | Met | Real detached linked-worktree regression proves its own cwd, index, and owner-relative staged path. |
| AC-003 | Met | Materialized contract JSON has repository-relative Owner paths and no own root. |
| AC-004 | Met | Missing Owner path output contains owner, command kind, resolved cwd, and ENOENT/message. |
| AC-005 | Met | Existing no-staged, aggregate failure, deletion exclusion, root/nested scoping, and read-only behavior tests remain GREEN. |
Runtime Validation Evidence
| Task | Scenario and target | Public action | Provenance | Expected and observed result | Cleanup | Status |
|---|---|---|---|---|---|---|
| T1 | Canonical runner in a real temporary repository and detached git worktree add --detach worktree | Execute node <runner> --contracts .devpunks/contracts.json with a staged linked-worktree file and stale Legacy root | Unique commit-gate-runner-* and commit-gate-runner-linked-* temporary roots created by the focused test | Marker output was written beneath the linked worktree and contained its top-level cwd plus owner-relative linked.ts; missing-owner output contained owner, command kind, resolved cwd, and ENOENT/message | afterEach removes the linked worktree through its primary repository, then removes only test-created roots | Passed |
Skill Application Evidence
| Task | Skill | Status | How and where |
|---|---|---|---|
| T1 | tdd | partial | The initial recovered pre-fix RED grouped three public-boundary failures before one seven-test GREEN, so it is recorded as an aggregate-suite deviation; later whitespace and carriage-return repairs each retained focused RED→GREEN evidence. |
| T1 | codebase-design | applied | The runner executable remains the public seam; Git root discovery and child-process launch metadata remain internal. |
| T1 | quality-types | applied | The declaration drops obsolete required root; launch metadata is derived at the child-process boundary. |
| T1 | simplify | applied | Obsolete contract.root execution authority was removed; active-worktree and owner-cwd derivation remain local to the runner, with shared test-marker cleanup as supporting simplification. |
| T2 | tdd | not_applicable | Coverage-only evidence for already-correct production behavior: no artificial RED was claimed and the focused GREEN was run. |
| T2 | codebase-design | applied | Assertions target materialized .devpunks/commit-gate-contracts.json, not private planner internals. |
| T2 | quality-types | applied | Effect Schema decodes boundary JSON once and validates each path before use. |
| T2 | simplify | applied | Existing planned-output fixture is reused with no duplicate producer setup. |
| T3 | writing-for-agents | applied | One concise positive operational invariant was added at the existing Commit Gate lifecycle pointer. |
| T3 | simplify | applied | The update is local and the root/routed runbook wording is identical. |
UI Evidence Links
Not applicable: issue #204 changes a CLI commit-gate runner, tests, and operator documentation; it has no visual UI surface.
Behavior Verification Evidence
No browser-visible acceptance criterion exists. CLI behavior is verified through the executable runner boundary and the correlated runtime row above.
Manual Review Checklist
| Area | Check | How to perform | Expected result |
|---|---|---|---|
| Portable execution | Re-run the focused executable scenarios | bun run --cwd apps/cli test -- src/data/scripts/commit-gate-runner.test.ts src/scaffold/output.test.ts | Both files and all contained tests pass, including stale Legacy root, linked worktree, missing Owner path, and rootless generated contract cases. |
| Diagnostics | Inspect the missing-owner assertion and runner failure rendering | Review commit-gate-runner.test.ts and commit-gate-runner.mjs | Output names the owner, kind, resolved cwd, and launch cause while retaining command output. |
| Stack | Verify the child PR base after closeout | gh pr view <child-pr> --json headRefName,baseRefName | Head is team/stefan/issue-204-portable-commit-gates; base is fix/issue-203-scaffold-convergence. |
Remaining work
No implementation debt or unmet acceptance criteria. The existing child PR still needs the final repaired commits pushed and its stack state verified during lifecycle closeout.
Deployment debugging closeout
PR #210's first Vercel wiki deployment failed during the production Next.js build because the retained review artifacts use the review contract's required review-report-json fence and Shiki did not bundle that custom language. The reports themselves validated against the review helper, and Fumadocs reached them through the expected wiki route, ruling out malformed evidence and missing content metadata.
Bare alias experiments are retained as failed history. The final deployed resolution spreads Fumadocs rehypeCodeDefaultOptions, explicitly preloads json and shellscript, and aliases review-report-json to json; it preserves the default themes and ordinary supported fences. Commit ecb4e10b39309ee6c2e92c70cf018bc64d79b349 has a successful Vercel deployment, and the current full local wiki production build passes. No debug endpoint, marker, or session identifier remains in production source.
Review and docs ingest
Review pass 1 repair staged the required bundled digest, clarified runner/tests and skill evidence, completed wiki metadata, restored the 50-entry log cap, and replaced broad Git-root trimming with terminal-newline handling. Review pass 2 found that CRLF handling could truncate a valid trailing carriage return and that linked-worktree teardown ignored Git cleanup failures. Repair 2 test-drove exact terminal-LF removal, hardened cleanup reporting, refreshed the bundled digest, and passed focused and combined validation. The next composite review found that the declaration had dropped syntactic compatibility for legacy root, two documentation claims overstated full-file alignment, and the projected review counters lacked retained-report authority. Repair 3 restores root as optional and explicitly non-authoritative, narrows the alignment claims, and resets the counters rather than inventing historical retained reports. Focused validation passed: runner/output tests 28/28, CLI typecheck, changed-file formatting, CLI build, wiki content sync, Fumadocs generation, and diff check.
The first valid retained review under the recovered lineage is commit 7a8443159e3032d1343be4420520f32dbc0b4ff3, report hash 7ac39abf188198e0a680e0d9b6151249ad417bea16a51e8966b7fb5f018308cf. Its sole finding, i204-spec-001, observed that the linked-worktree fixture omitted the stale legacy root claimed by the runtime-evidence row. Repair 1 added that obsolete absolute root to the existing linked-worktree contract while retaining the linked checkout, index, and staged-path assertions; the focused runner suite remained GREEN at 9/9. Retained review 2 at commit cd2bfbf259fb331be77d437afa7ea3b00ecf4527 is clean across all five lenses and structured autoreview, with report hash e6f43f62b3e30fdcea1061c085888a6e812dca0397ae915715adf6ccdd6f1934. Retained review 3 is committed as 1e6e0d556082599015822266e5841eda0059f923 with report hash 933279c86e72f959ba9f507c1fdaef6fc0a3676e00fce2377445e190fe59ddd5; its sole stable finding, i204-sa-001, is repaired above by recording T2 as not_applicable for coverage-only evidence. Its primary route is docs_ingest; it requires no fourth review and introduces no debt. Docs ingest kept the existing Commit Gate lifecycle runbook as the flow and future-use hook, added no duplicate concept page, and finalized this bookkeeping for closeout. See PHASE-HANDOFF.md for routed state.