# repository Guardrails

> Canonical path: `guardrails/repository/README.md`

This README lists executable guardrails for the `repository` domain in recommended order.

- [`specs-and-guardrails-layout.sh`](./specs-and-guardrails-layout.sh)
- [`check-agent-entry-skills.sh`](./check-agent-entry-skills.sh)
- [`check-skills-layout.sh`](./check-skills-layout.sh)
- [`check-go-package-names.py`](./check-go-package-names.py) — requires
  lowercase package names without underscores, package/directory basename
  alignment, matching package comments, and no retired full import strings in
  non-Go text; excludes `x/` and the repository-analysis fixture. Run together
  with its focused tests via `make check-go-package-names`.
- [`check-code-shape.py`](./check-code-shape.py)
- [`check-test-quality.py`](./check-test-quality.py)
- [`check-performance-static.py`](./check-performance-static.py)
- [`check-frontend-quality.py`](./check-frontend-quality.py)

## Fast harness debt ceilings

`scripts/harness-fast.sh` owns the active ceilings for these inventory
guardrails. Re-run the inventory at the branch head before changing a ceiling,
and never trade a decrease in one metric for an increase in another.

| Inventory | Active ceilings | Debt owner | Why the debt is temporarily accepted | Retirement condition |
| --- | --- | --- | --- | --- |
| Code shape | files over 1,000 lines `119`; files over 2,000 lines `21`; Go functions over 120 lines `203`; thin Go wrappers `1301` | Owners of the production packages printed by `check-code-shape.py`; `guardrails/repository` owns measurement | A cross-repository rewrite would mix unrelated package changes and make ownership less clear; the integrated #t2587 head adds 2 thin wrapper seams from the merged upstream ONES extension (`ones/schemas.go`), the #t2751 clean integration carries the required truncation-receipt digest in `internal/workflow/run/reducer.go` (2037 lines) plus 3 structured-error/event-contract forwarding wrappers (`workflowbinding/errors.go`, `workflowrun/event_effect_schema.go`, `workflow/run/failure_identity.go`), the upstream #t2667 cycle-6 corrections add recovery/session-fence seams, and the reviewed #t2886 Task parent-authority cutover adds the canonical parent/readable SQL surface and lifecycle fences | Split or delete debt in the package being changed, then lower the matching ceiling in the same change; keep ratcheting toward zero |
| Test quality debt | fixed waits `59`; test files over 800 lines `155`; source-assertion test files `220`; TiDB fixture calls inside subtests `34` | Owners of the first-party test suites printed by `check-test-quality.py`; `guardrails/repository` owns measurement | Existing suites still combine broad scenarios, timing-based synchronization, assertions over production source text instead of executable behavior, and repeated database provisioning inside scenario matrices; the integrated #t2587 head merges upstream web tests (`textareaResize.test.ts`, Jenkins connection section test) and carries one pre-existing large chain test file plus the authoritative Workflow error-surface component regression (`WorkflowRunNowDialog.test.tsx`) | Replace fixed waits with observable conditions, split suites at behavior boundaries, replace source-text assertions with behavior tests or executable guardrails, and provision one rollback database outside serial subtests when fixtures use disjoint identifiers; lower each ceiling on every decrease |
| Test quality zero targets | overbroad mocks `0`; snapshots `0`; focused tests `0`; skipped tests `0` | All test owners | These patterns are not accepted debt | Keep each ceiling at zero |
| Static performance debt | production sleeps `3`; DB calls in loops `40` | Owners of the runtime packages printed by `check-performance-static.py`; `guardrails/repository` owns measurement | The remaining waits and per-item database work require behavior-preserving, package-local migrations | Replace sleeps with cancellation-aware signals and batch database operations; lower each ceiling on every decrease |
| Static performance zero targets | `SELECT *` `0`; uncancellable timer waits `0` | All production package owners | These patterns are not accepted debt | Keep each ceiling at zero |
| Frontend quality debt | polling intervals `5`; uncapped `Promise.all` `13`; direct buttons outside shared UI `214`; compatibility CJK literals `6` | Owners of the files printed by `check-frontend-quality.py`; `web/src/agentteam` owns the shared primitives and compatibility parser | Existing polling/concurrency call sites and native buttons need behavior-aware migrations; the CJK strings parse persisted cross-locale mirror notes without eagerly loading locale bundles | Move polling to event-driven or bounded refresh, cap dynamic fan-out, adopt shared buttons, and retire literals only when persisted notes have a locale-independent format; lower the matching ceiling on every decrease |
| Frontend quality zero targets | direct fetch outside the API client `0`; direct input outside shared UI `0` | All `web/src/agentteam` owners | These patterns are not accepted debt | Keep each ceiling at zero |

An increase requires a reviewed scope plus an updated owner, reason, and
retirement condition here. A cleanup must lower the corresponding ceiling in
the same change so deleted debt cannot be replaced elsewhere.

## Related domain guardrails

- [`../architecture/check-service-automation-architecture.sh`](../architecture/check-service-automation-architecture.sh) protects the Service Actor / Service Event / Schedule / Automation migration boundary.