Foundation Quality Gates¶

Status: STABLE TECHNICAL STANDARD / NOT PHASE OR TASK AUTHORITY
Documentation authority: ../README.md
Development standard: ../DEVELOPMENT.md
UUID standard: UUID_IDENTITY_TRANSITION_STANDARD.md

This document owns reusable gate definitions. ROADMAP owns phase scope; the selected Task document owns its exact acceptance scenarios, environment and evidence.

1. Gate Model¶

ZERO_TOLERANCE = blocks the changed slice
RATCHET        = accepted measured baseline cannot regress without approval
TRIGGERED      = applies only when the slice introduces the trigger
ACCEPTANCE     = actual role/data/runtime evidence

A source or unit-test pass cannot replace required runtime/data evidence. An inapplicable gate is NOT_APPLICABLE, not a reason to build missing infrastructure.

2. Product-Throughput Gate¶

An IMPLEMENT slice requires:

one observable operator result;
an immediate consumer for every new abstraction;
bounded paths and effects;
production code and focused tests;
applicable authoritative readback.

A product implementation request is not closed with documents and reused code alone. Where a document, tool or test is the requested result, the applicable acceptance criteria are used. Foundation code with no consumer, or a ceremonial Work Graph, is not created. The default limit on change scope is ROADMAP, and the approval condition for adding structure is referenced from Gate 6 of the Architecture Change Method. The per-page Playwright script uses the existing matching spec under scripts/tests/e2e/pages/. The page contract, the Task and the test guide link the exact file and execution command. Existing execution and evidence paths are preserved, and replacing a runner follows an approved decision. ROADMAP owns the phase scope; the matching acceptance Task document owns the real user flow, environment, owner and execution evidence. Task selection and handoff follow the Task standard.

3. Architecture Gates¶

Block changed canonical code on:

package cycles, deep or undeclared imports;
app-to-app imports;
module imports of concrete DB/provider/UI implementations;
React/Next outside admitted Web/UI packages;
SQL outside DB adapters, migration or registered DB tooling;
process.env outside config/bootstrap;
DB/provider types exported publicly;
unbounded business Record<string, unknown> contracts;
cross-module repository/table access;
route handlers owning SQL, transactions or business state;
browser imports of server-only code;
mutable process-wide request/tenant state;
root Legacy runtime dependency from canonical routes;
direct canonical-page window.KJ* dependency;
a new generic catch-all API as target architecture.

4. UUID And Tenant Gates¶

Block on:

numeric entity/tenant identity in canonical route, payload, command, query, UI state, cache, audit or job;
UUID and numeric aliases exposed together;
client-supplied numeric alias used for authority;
numeric alias outside approved DB compatibility;
UUID binary representation outside DB adapters;
one-sided, orphaned, mismatched or cross-tenant dual keys;
non-atomic required dual-key writes;
authoritative reread by numeric identity;
null/nil/duplicate canonical UUID in the accepted cohort;
tenant-owned operation without explicit tenant UUID scope and negative test.

UUID is not authorization.

5. Security Gates¶

Block on:

missing server-side authorization;
request-controlled tenant authority;
foreign-tenant active-reference acceptance;
feature visibility used as permission;
secret/session/password/protected file content in logs or client payload;
Production secret fallback;
unsafe origin/CSRF handling on cookie mutation;
open redirect or account enumeration;
unparameterized SQL or unrestricted dynamic query shape;
unbounded upload/list/search;
privileged action without positive and denied tests;
swallowed unexpected authentication/security errors.

6. Data And Reliability Gates¶

Block on:

SELECT * in canonical query/readback;
mutation without affected-row/conflict classification where absence matters;
remote provider inside an open DB transaction;
blind retry after unknown mutation result;
duplicate writer for one request class;
missing authoritative readback;
inconsistent lock order;
non-idempotent retry without unique/idempotency/readback protection;
hidden partial effect;
test mutation without deterministic cleanup/readback;
breaking an active Legacy rollback reader without cutover authority.

7. Triggered Capability Gates¶

Apply a capability gate only when the changed slice introduces its trigger. A DB mutation requires transaction/conflict/idempotency/readback; a remote provider requires timeout, classified error and manual recovery; durable remote effects or background work require persistent identity/reconciliation or a real persistent source/consumer/lease/fencing/backoff/dead-letter respectively. Do not build those facilities before their trigger exists.

Files And Photos¶

Require bounded type/size, checksum/object identity, same-tenant entity reference, object/relation separation, upload/relation/delete readback, partial-effect cleanup/reconciliation, reference-safe delete, bounded image processing, relation/order conflict handling and no public numeric entity ID.

Documents¶

Require typed source projection, source/template revision, source validation separate from rendering, preview separate from durable output, output separate from provider delivery, deterministic rendering and no source mutation by renderer.

AI¶

Require authorized source, provider timeout/classified error, typed extraction, field-level mapping/validation, user review, apply to unsaved state only, no automatic business save, manual fallback, safe retry and no secret/protected content in telemetry.

An intercepted browser response is supporting UI evidence, not proof of an owned provider adapter.

8. Web And UI Gates¶

Block on:

required route implemented only by mock/stub;
global synchronous route-local feature script;
inaccessible primary action, dialog close or table navigation;
focus loss after workspace close;
missing loading/empty/error/retry state;
duplicate writer across surfaces;
numeric row position/ID as canonical UI key;
required actual-route test skipped but reported as pass;
critical console error in an accepted journey.

9. Review Budgets¶

Measure	Review threshold	Hard threshold without accepted rationale
production source file	300 logical LOC	500
React component/module	200	350
function/hook/handler	50	100
complexity	10	15
route handler	60	100
direct package dependencies	12	20

Threshold breach triggers semantic review, not arbitrary file splitting. Copied/vendor source is measured separately; adapters and canonical consumers are not exempt.

10. Evidence And Tests¶

Use existing test/lint/type/build tools. Do not create a parallel quality platform.

Applicable layers:

unit / policy / invariant
UUID / schema / contract
component / plugin adapter
real MySQL repository / transaction
authenticated actual route
fault / concurrency / partial effect
provider adapter
accessibility / performance
cleanup / reconciliation

skipped means NOT_RUN;
required tests do not rely on retry;
fixtures have owner and cleanup;
mocks/screenshots are supporting evidence only.

10.1 Page Acceptance Contract¶

A canonical page with a Task-declared page-specific acceptance contract uses the change-scoped update matrix. These requirements apply to selected changed behavior and required acceptance, not every internal move. They retain the page proof from Decision 0007.

Keep the selected page contract, executable page script, runtime/readback evidence, Wiki verification, append-only Process history and catalog relations synchronized in the same Task and commit. Implement/update the affected contract and script, execute the actual route, verify authoritative readback, capture named passing scenarios, update affected manual/history metadata, then validate versions and required in-app rendering before claiming acceptance. Missing required runtime, fixture, capture or Wiki build is BLOCKED; an unexecuted check is NOT_RUN.

A prototype, UI Catalog story, unit/component/DOM snapshot, manually captured screenshot or generic shared browser test does not replace that script or its required actual-route execution. Use a running local or explicitly authorized QA route, actual page composition and approved fixture/query/command adapters or isolated MySQL fixture. Distinguish adapter fixtures from real DB proof; do not infer DB/provider acceptance from mocked responses.

Change the script when the page or its popup/modal/drawer interaction contract, scenario metadata or evidence changes. Update affected steps/assertions/capture points, pageContractVersion and validatedAgainstChangeId truthfully; preserve unaffected scenarios. No-op comments do not qualify. For shared UI changes, test the shared contract and representative affected consumers, with specific page changes where their contracts/evidence changed. An unchanged internal refactor does not force a Wiki or page-version bump. Visual-only changes with unchanged Process record Process impact: NONE when history is applicable; still supply the required visual/regression evidence.

10.2 Scenario And Version Contract¶

Declare script metadata pageId, pageContractVersion, validatedAgainstChangeId, wikiArticleId and evidenceManifest. Page contract, catalog, script, evidence manifest, Wiki verification and latest applicable CHANGELOG entry agree on page identity and contract version. The change ID identifies the append-only history entry, not a substitute for an actual test run.

Stable scenario IDs such as <page-id>.SCN-010 connect test titles/annotations, TEST_MATRIX.md, evidence-manifest.yaml, Wiki screenshot metadata and changed-scenario history. Page-owned sub-surfaces may share the parent package only with scenarios/captures/history registered under its page ID. Existing page contracts name their test path, scenario/capture states, Wiki article ID/route, contextual Help mapping and CHANGELOG location; do not scaffold unused per-page files.

Select applicable coverage and record NOT_APPLICABLE with a reason for excluded dimensions:

Dimension	Required scenarios when applicable
Entry and normal use	assigned menu/Product surface; direct route/bookmark; normal load and primary task; authoritative mutation save/readback
States and rejection	loading, empty, not-found; validation/rejection; denied versus unavailable/unknown
Reliability and recovery	duplicate/stale/concurrent data; timeout/unknown-result/check-before-replay; correction, reversal, reopen, retry or reconciliation
Interaction and variation	keyboard/focus/accessibility; approved tenant/profile/role variation; compatibility popup open/save/cancel/close/focus/parent return
Transition and help	return-to-Legacy/fallback before cutover; contextual Help and in-app User Wiki rendering

Fixtures record tenant/profile, role/capabilities, source records/state, safe identifiers, setup and cleanup, clock/timezone and provider/file/device adapters. Never commit Production customer data, secrets or credentials as evidence.

10.3 Screenshot, Wiki And History Evidence¶

A manual screenshot comes from a named passing runtime scenario. Record page ID/contract version, scenario ID, profile/tenant fixture, role, viewport, fixture ID, runtime/release revision, path, SHA-256, capture time, Wiki article/section and result = PASS. Raw traces, videos, retry captures and unreviewed screenshots remain in .generated/browser-evidence/<page-id>/. Only reviewed, article-referenced captures are published through the existing Wiki asset API to T_FILE and the configured object store; the article Markdown stores its wiki-asset://<UUID> reference. Manual file copying is not publication, and manual copying without provenance validation is not promotion. Never substitute prototype images for required implemented-runtime evidence.

Wiki README owns manual behavior, build/registry/route ownership and live-catalog selection. Operational article source is T_WIKI_PAGE; developer specifications retain their Git owners and remain read-only in the Wiki. For the selected workflow, verify the actual article, App Shell/search entry and contextual Help mapping, approved theme and accessibility, and approved profile/role differences. Preserve current Client-specific manual scope; this standard does not publish a new article or expose every generated article automatically.

The article explains purpose/operator/timing, how to open it, visible prerequisites, primary steps, statuses/actions, validation/errors/recovery and approved role/profile differences. Keep each passing capture next to the step/result it proves. Developer metadata, table/class names, hidden actions and evidence status do not belong in operator-facing prose. Store verifiedAgainstPageContractVersion, scenario IDs and runtime revision in verification metadata, not visible instructions. When the Task requires a changed page script to rerun, update its article verification metadata even if the operator steps remain accurate. An unrelated internal move requires no no-op manual edit.

Changed business or recovery contracts append to docs/pages/<domain>/<page-slug>/CHANGELOG.md. Preserve change ID/date, page version, before/after behavior, Process impact: <IDs> | NONE, command/query/policy/state, field/action/access/read-model, transaction/effect/recovery and Legacy/fallback impacts; link changed scenarios/script, screenshots/ manifest and Wiki sections; record rollback boundary and remaining unknowns. Git history alone does not explain these operator consequences. Do not remove existing page scripts, Wiki content, evidence manifests or histories merely because the shared instructions were consolidated.

10.4 Local Commands And Evidence Limits¶

Use package.json, tests/README and the selected Task for actual runnable commands, not a historical handover's proposed CLI. pnpm test:page invokes the existing Playwright configuration; its arguments are runner arguments, not a promised <page-id> API. Operational manuals are verified by DB UUID/metadata/asset readback plus the authenticated API and rendered screen.

At this source revision, page:evidence:capture, page:evidence:validate and wiki:evidence:promote print NOT_EVIDENCE guidance to stderr and exit non-zero instead of the former TASK_SCOPED placeholder text; they do not capture, validate or promote evidence. page:change:validate runs the docs validator and is not proof that every page's runtime/version/history was checked. Run the concrete accepted Task's capture/verification procedure when required. Version parity, scenario registration, checksum matching, actual article/Help rendering and applicable history must be proved by their real checks; a named command or zero exit status alone is not that proof.

Keep source/static verification, authenticated browser/role/readback, Wiki generation and release results separate. No hosted CI or GitHub Actions. Production deployment, customer data, DB mutations, provider/file/device effects, route/writer cutover and external publication need their own authority.

11. Performance Ratchet¶

Measure comparable roles, data and environment.

no unexplained critical p95 regression greater than 10%;
initial route bundle does not absorb lazy feature assets;
no unbounded query or table scan;
no unexplained DB roundtrip growth;
the applicable phase acceptance contract defines required material improvements.

Absolute budgets come from measured baseline, not invention.

12. Acceptance Selection¶

Passing these generic gates does not by itself authorize the next phase, deployment, cutover or retirement.¶

Source: new-system/docs/architecture/FOUNDATION_QUALITY_GATES.md — ctc repository · This page is an English translation of the source document. Identifiers, file paths and code symbols are unchanged. A user instruction quoted inside the text is kept in its original language.