fix(gates): allow explicit structure-debt bypass (sc-1528)

[norvalbv]

Summary

• add an explicit one-run GUARD_STRUCTURE_OK=1 bypass, with GUARD_NO_STRUCTURE as a compatibility alias
• skip only the configured structure-lint command while preserving every other deterministic gate
• make bypass use loud output, collector-supported non-run telemetry, and a distinct prefix-cache scope
• avoid re-emitting bypass output or telemetry when a retry is served by the prefix cache
• document the escape hatch in devkit help ship and cover it with regression tests

Root cause

devkit ship passed the configured structure command to the deterministic orchestrator as an arbitrary whole-tree ESLint invocation. Because that raw command never entered guard-structure, an escape hatch implemented inside the structure checker could not help repositories carrying pre-existing structure debt.

Validation

• reproduced Story #1528 against Frink commit 7a87f35ce5eb93db52b6d8523c6ce9afc98547ee: without the flag the gate reports the five known base-tree errors; with the flag it exits successfully and prints the bypass warning
• focused deterministic tests: 57/57 passed, including cache-hit retry and telemetry reader-contract coverage
• isolated TypeScript check: passed
• GitNexus change detection: three intended symbols, four affected gate flows, medium risk
• commit guard: no clone or semantic duplication findings

Full-suite note

The shared checkout full suite was also attempted. It is currently blocked by unrelated concurrent edits in the review setup modules and one pre-existing process-reaping timing failure; the isolated clean-base typecheck and all focused tests for this change pass.

Summary by CodeRabbit

• New Features
  • Added an explicit per-run option to bypass structure checks using GUARD_STRUCTURE_OK=1 or its supported alias.
  • Bypassed runs display a clear warning and continue enforcing all other checks.
• Bug Fixes
  • Improved structure-check failure messages with guidance for rerunning when an intentional bypass is required.
  • Ensured bypassed and standard runs remain isolated for consistent validation results.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 1fc88fd8-90a2-4055-95a7-819b3dba528a

📥 Commits

Reviewing files that changed from the base of the PR and between ceb9f94 and 4e905c9.

⛔ Files ignored due to path filters (3)

• dist/cli/commands/ship.mjs is excluded by !**/dist/**
• dist/gate-engine/config.mjs is excluded by !**/dist/**
• dist/gate-engine/deterministic/run.mjs is excluded by !**/dist/**

📒 Files selected for processing (4)

• cli/commands/ship.mts
• gate-engine/config.mts
• gate-engine/deterministic/__tests__/run.test.mts
• gate-engine/deterministic/run.mts

---

📝 Walkthrough

Walkthrough

The change adds per-run structure-lint bypassing through two environment flags. The deterministic runner records bypass telemetry, isolates cache scopes, preserves other gates, emits warnings, and provides remediation guidance. Tests cover execution, telemetry, logging, and cache behavior.

Changes

Structure bypass flow

Layer / File(s)	Summary
Bypass contract and command guidance gate-engine/config.mts, cli/commands/ship.mts	The structureBypassed() predicate recognizes GUARD_STRUCTURE_OK=1 and GUARD_NO_STRUCTURE=1. The ship command documents their usage constraints and telemetry behavior.
Runner execution and cache handling gate-engine/deterministic/run.mts	The runner applies a separate structure-bypassed cache scope, records bypass telemetry, omits structure checks, prints warnings, and adds structure-specific failure guidance.
Bypass behavior and cache tests gate-engine/deterministic/__tests__/run.test.mts	Tests cover both flags, preserved deterministic gates, telemetry, warning suppression on cache hits, failure guidance, environment cleanup, and composed cache salts.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant ShipCommand
  participant DeterministicRunner
  participant PrefixCache
  participant Telemetry
  ShipCommand->>DeterministicRunner: start run with structure bypass flag
  DeterministicRunner->>PrefixCache: select structure-bypassed cache scope
  DeterministicRunner->>Telemetry: emit could_not_run event
  DeterministicRunner->>DeterministicRunner: skip structure gate
  DeterministicRunner->>ShipCommand: continue with other deterministic gates

Loading

Possibly related PRs

• norvalbv/devkit#349: Extends the deterministic gate opt-out framework in the same configuration and runner modules.
• norvalbv/devkit#148: Uses a related per-run bypass pattern across command, configuration, telemetry, and cache-scope code.
• norvalbv/devkit#47: Modifies deterministic prefix-cache salting for structure-related gate configuration changes.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the explicit structure-debt bypass added by this pull request.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/sc-1528-structure-base-debt-bypass

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}