Merge lane/S: deletable history docs, ungated script check, production drills on the promoted archive (11-04, 00-02, 14-05, 12-04, 13-03)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
donghyeon-ka
2026-09-28 00:59:08 +09:00
co-authored by Claude Opus 5.5
19 changed files with 633 additions and 36 deletions
+9 -1
View File
@@ -368,12 +368,13 @@ jobs:
production_gate:
name: "${{ matrix.gate }} / ${{ matrix.name }}"
needs: promotion
needs: [immutable_build, promotion]
if: ${{ gitea.event_name == 'workflow_dispatch' && (inputs.stage == 'production' || inputs.stage == 'field') }}
runs-on: ubuntu-latest
timeout-minutes: 45
env:
HOSTING_BASE_URL: "${{ vars.HOSTING_BASE_URL }}"
CANDIDATE_ARCHIVE_SHA256: "${{ needs.immutable_build.outputs.archive_sha256 }}"
strategy:
fail-fast: false
matrix:
@@ -395,6 +396,13 @@ jobs:
run: |
corepack enable
corepack pnpm install --frozen-lockfile --ignore-scripts
- name: Download promoted release
uses: https://github.com/ChristopherHX/gitea-download-artifact@75635f32b4c1c41c4b3d64e8f85210112ed4c9c7
with:
name: "promoted-release-${{ gitea.run_id }}-${{ gitea.run_attempt }}"
path: .release/promoted
- name: Verify and extract the candidate through one inode-bound operation
run: node scripts/verify-ci-candidate-archive.ts --archive ".release/promoted/release-candidate.tar.gz" --extract-to ".release/promoted-release"
- name: Run blocking gate
run: corepack pnpm ci:gate -- ${{ matrix.gate }}
- name: Upload production gate evidence
+2 -1
View File
@@ -192,7 +192,8 @@ target designs and work history.
### Files you can delete after copying
These record how the template was built. Nothing in the build or the gates
reads them, except the one file noted below.
reads them, except the one file noted below
(`tests/unit/deletable-history-documents.test.ts` checks this).
| Path | Contents |
| --- | --- |
+4 -4
View File
@@ -1,11 +1,11 @@
{
"schemaVersion": 1,
"owner": "frontend-platform",
"reason": "13-05 (D-14): FE-GATE-019 probes the deployed promoted release in the production stage; the fixture is UNVERIFIED",
"reason": "13-03: production_gate downloads the promoted archive and FE-GATE-021..025 drill it with --release-root instead of rebuilding",
"gates": 27,
"commands": 95,
"commandReferences": 105,
"commands": 98,
"commandReferences": 103,
"artifacts": 109,
"stages": 5,
"gateShapeSha256": "648066f2ba0dd38c3193550ecb4bd030a2e0f66027919256648f78333564db3c"
"gateShapeSha256": "630e801239de5d175fd1049b2527851dabe06f139ba8ff6a98de7f09f7a257c2"
}
+48 -10
View File
@@ -309,6 +309,16 @@
"script": "check:architecture",
"expect": "pass"
},
{
"id": "check-request-fanout",
"script": "check:request-fanout",
"expect": "pass"
},
{
"id": "check-app-build-input",
"script": "check:app-build-input",
"expect": "pass"
},
{
"id": "check-design-system",
"script": "check:design-system",
@@ -421,6 +431,11 @@
"script": "check:bundle",
"expect": "pass"
},
{
"id": "check-app-build-input-bundle",
"script": "check:app-build-input:bundle",
"expect": "pass"
},
{
"id": "check-optional-recipes",
"script": "check:optional-recipes",
@@ -471,7 +486,9 @@
"script": "drill:runbook",
"args": [
"--",
"FE-RB-005"
"FE-RB-005",
"--release-root",
".release/promoted-release"
],
"expect": "pass"
},
@@ -515,7 +532,9 @@
"script": "drill:runbook",
"args": [
"--",
"FE-RB-001"
"FE-RB-001",
"--release-root",
".release/promoted-release"
],
"expect": "pass"
},
@@ -524,7 +543,9 @@
"script": "drill:runbook",
"args": [
"--",
"FE-RB-002"
"FE-RB-002",
"--release-root",
".release/promoted-release"
],
"expect": "pass"
},
@@ -533,7 +554,9 @@
"script": "drill:runbook",
"args": [
"--",
"FE-RB-003"
"FE-RB-003",
"--release-root",
".release/promoted-release"
],
"expect": "pass"
},
@@ -542,7 +565,9 @@
"script": "drill:runbook",
"args": [
"--",
"FE-RB-004"
"FE-RB-004",
"--release-root",
".release/promoted-release"
],
"expect": "pass"
},
@@ -1885,6 +1910,8 @@
"name": "architecture",
"commandIds": [
"check-architecture",
"check-request-fanout",
"check-app-build-input",
"check-design-system",
"check-design-system-fixture",
"check-i18n",
@@ -1946,6 +1973,7 @@
"commandIds": [
"build",
"check-bundle",
"check-app-build-input-bundle",
"check-optional-recipes"
],
"logArtifactId": "artifact-artifacts-quality-gates-FE-GATE-012-txt",
@@ -2079,7 +2107,6 @@
"id": "FE-GATE-021",
"name": "runbook-boot-config",
"commandIds": [
"build",
"drill-runbook-2"
],
"logArtifactId": "artifact-artifacts-quality-gates-FE-GATE-021-txt",
@@ -2092,7 +2119,6 @@
"id": "FE-GATE-022",
"name": "runbook-chunk-mismatch",
"commandIds": [
"build",
"drill-runbook-3"
],
"logArtifactId": "artifact-artifacts-quality-gates-FE-GATE-022-txt",
@@ -2105,7 +2131,6 @@
"id": "FE-GATE-023",
"name": "runbook-api-degradation",
"commandIds": [
"build",
"drill-runbook-4"
],
"logArtifactId": "artifact-artifacts-quality-gates-FE-GATE-023-txt",
@@ -2118,7 +2143,6 @@
"id": "FE-GATE-024",
"name": "runbook-telemetry",
"commandIds": [
"build",
"drill-runbook-5"
],
"logArtifactId": "artifact-artifacts-quality-gates-FE-GATE-024-txt",
@@ -2131,7 +2155,6 @@
"id": "FE-GATE-025",
"name": "runbook-release-rollback",
"commandIds": [
"build",
"drill-runbook"
],
"logArtifactId": "artifact-artifacts-quality-gates-FE-GATE-025-txt",
@@ -2747,6 +2770,7 @@
"displayName": "${{ matrix.gate }} / ${{ matrix.name }}",
"kind": "gate-matrix",
"needs": [
"immutable_build",
"promotion"
],
"condition": "production",
@@ -2764,6 +2788,10 @@
{
"name": "HOSTING_BASE_URL",
"value": "${{ vars.HOSTING_BASE_URL }}"
},
{
"name": "CANDIDATE_ARCHIVE_SHA256",
"value": "${{ needs.immutable_build.outputs.archive_sha256 }}"
}
],
"steps": [
@@ -2776,6 +2804,16 @@
{
"kind": "frozen-install"
},
{
"kind": "download",
"transferId": "promoted-release",
"path": ".release/promoted"
},
{
"kind": "extract",
"archivePath": ".release/promoted/release-candidate.tar.gz",
"targetRoot": ".release/promoted-release"
},
{
"kind": "run-gate"
},
+73
View File
@@ -0,0 +1,73 @@
{
"schemaVersion": 1,
"entries": [
{
"script": "check:feature-index",
"reason": "The generated indexes (src/.generated/) are not committed, and every gate script regenerates them first (generate-product-feature-index.ts), so --check can only tell a developer that the local copy is stale."
},
{
"script": "check:http-scenario-evidence",
"reason": "Run by scripts/run-http-scenario-evidence.ts, which is test:http-scenario-evidence in FE-GATE-007; that runner calls it by name after the scenario catalog."
},
{
"script": "check:http-scenario-evidence:fixture",
"reason": "Negative fixture run by scripts/run-http-scenario-evidence.ts (test:http-scenario-evidence, FE-GATE-007), which requires it to fail with TEST-EVIDENCE-EXECUTION-ID-MISSING."
},
{
"script": "check:remediation-ledger",
"reason": "Checks the prose ledger of the 2026-08-14 adapter re-review (docs/operations/adapter-remediation-ledger.md) against test-file markers and the file-transfer bundle budget. Later fixes removed those markers and the budget is re-set at integration, so the check reports stale claims at this commit. It is a history record run by hand, not a current contract; wiring it into a gate first needs the ledger or the markers brought up to date."
},
{
"script": "check:scale:baseline",
"reason": "Scale tier outside CI (scripts/scale/run-scale-profile.ts): it includes baseline-regression, which compares timings only on the CPU model that recorded config/scale/benchmark-baseline.json and reports incomplete elsewhere (review 11-03). Run it on that machine. The CPU-independent pr tier runs in FE-GATE-005."
},
{
"script": "check:scale:main",
"reason": "Scale tier outside CI (scripts/scale/run-scale-profile.ts): it includes baseline-regression, which compares timings only on the CPU model that recorded config/scale/benchmark-baseline.json and reports incomplete elsewhere (review 11-03). Run it on that machine. The CPU-independent pr tier runs in FE-GATE-005."
},
{
"script": "check:scale:nightly",
"reason": "Scale tier outside CI (scripts/scale/run-scale-profile.ts): it includes baseline-regression, which compares timings only on the CPU model that recorded config/scale/benchmark-baseline.json and reports incomplete elsewhere (review 11-03). Run it on that machine. The CPU-independent pr tier runs in FE-GATE-005."
},
{
"script": "check:scale:release",
"reason": "Scale tier outside CI (scripts/scale/run-scale-profile.ts): it includes baseline-regression, which compares timings only on the CPU model that recorded config/scale/benchmark-baseline.json and reports incomplete elsewhere (review 11-03). Run it on that machine. The CPU-independent pr tier runs in FE-GATE-005."
},
{
"script": "check:test-evidence",
"reason": "Local all-in-one run. CI splits it: check:test-evidence:browser (--skip-scenario-executions) in FE-GATE-008 after the browser suites, and the scenario part through test:http-scenario-evidence in FE-GATE-007."
},
{
"script": "check:test-evidence:source",
"reason": "--source-only is a subset of check:test-evidence:browser (FE-GATE-008), for a quick local run without browser results."
},
{
"script": "drill:runbooks",
"reason": "Local shortcut for all five drills. CI runs each drill as its own production gate (FE-GATE-021 to FE-GATE-025) through drill:runbook."
},
{
"script": "test:all",
"reason": "Local aggregate of suites the gates run one by one (FE-GATE-004 to FE-GATE-007). The removal checks in FE-GATE-020 run it inside their fixtures through scripts/lib/removal-fixture.ts, not through the package script graph."
},
{
"script": "test:e2e:dev",
"reason": "Runs tests/e2e against the Vite dev server (playwright.dev.config.ts) for local debugging. FE-GATE-008 runs the same specs against the production build (test:e2e)."
},
{
"script": "test:extreme-scale:focused",
"reason": "Part of verify:extreme-scale. All its paths run in FE-GATE-005 except tests/scale/global-local-independence.test.ts, which belongs to the main scale tier (see config/ci/ungated-tests.json)."
},
{
"script": "test:visual:update",
"reason": "Rewrites the visual snapshots; it is an update command, not a check. FE-GATE-008 runs test:visual."
},
{
"script": "verify:extreme-scale",
"reason": "Local aggregate of 24 scripts (scripts/verify-extreme-scale.ts). Its CPU-independent parts run in gates; the main, nightly and release scale tiers need the baseline CPU (see check:scale:main)."
},
{
"script": "verify:promotion",
"reason": "Re-verifies a promotion bundle archived by an earlier run (13-04, --archived) with provider trust keys and EXPECTED_PROMOTION_* inputs of that run. In CI the promotion job verifies the same bundle through scripts/stage-verified-promotion.ts before it uploads it."
}
]
}
+41
View File
@@ -0,0 +1,41 @@
{
"schemaVersion": 1,
"baseline": "config/scale/feature-shape-growth.json",
"ceilings": {
"contextMaxFeatures": 200,
"appMaxContexts": 20
},
"summary": "The ceilings bound the count; they are not a verified capacity. The practical limit of one app is the initial JavaScript budget, then typecheck memory. 400 features were not measured (D-18 makes it optional).",
"axes": [
{
"axis": "Typecheck of one app",
"verified": "Linear, about 115k instantiations and 37 MB of tsc memory per feature, up to 100 features",
"condition": "Reference-shaped features, tsconfig.app.json, the host recorded in the baseline",
"notVerified": "200 features (one full context) and beyond; 4,000 (20 x 200) would need on the order of 150 GB by the same slope"
},
{
"axis": "Production build",
"verified": "Completes at 100 features in seconds",
"condition": "Same",
"notVerified": "Beyond 100"
},
{
"axis": "Initial JavaScript",
"verified": "Grows by about 2.9 KB gzip and one file per feature: every installed feature's contracts and module load at boot",
"condition": "Same",
"notVerified": "The initial budget (204,800 B, config/performance/budgets.json) is exceeded after a few more reference-shaped features, far below the context ceiling"
},
{
"axis": "Lazy JavaScript",
"verified": "About 6.8 KB gzip and six files per feature, every file far below the 120 KiB lazy-chunk budget",
"condition": "Same",
"notVerified": "Download cost of many lazy files"
},
{
"axis": "Routes",
"verified": "4 per feature, composed without conflict",
"condition": "Same",
"notVerified": "Router matching cost at runtime"
}
]
}
+1 -1
View File
@@ -43,7 +43,7 @@ README와 입구 문서는 영어, recipe·ledger·스타일 문서는 한국어
|---|---|
| `architecture/review-ledger.json`, `architecture/review-evidence.md`, `accessibility/manual-checklist.md` | `verify:documentation` (FE-GATE-017) |
| `reviews/adapters/INVENTORY.md` | `check:adapter-inventory` (FE-GATE-010) |
| `operations/adapter-remediation-ledger.md`, `operations/adapter-remediation-dispositions.json` | `check:remediation-ledger` |
| `operations/adapter-remediation-ledger.md`, `operations/adapter-remediation-dispositions.json` | `check:remediation-ledger` (게이트 밖. 이유는 `config/ci/ungated-scripts.json`) |
## 2. 목표 설계
+19 -3
View File
@@ -39,6 +39,13 @@ Playwright 설정의 `testDir`를 모아 비교한다(`scripts/lib/ungated-tests
게이트가 돌리지 않는 테스트는 `config/ci/ungated-tests.json`에 이유와 함께 적어야
한다. 게이트가 이미 돌리는 파일을 이 목록에 남겨 두면 실패한다.
package script도 같은 방식으로 확인한다(`scripts/lib/ungated-scripts.ts`).
`check:*`·`verify:*`·`test:*`·`drill:*`·`review:*` 스크립트는 게이트 명령에서
package script 그래프로 닿거나, 게이트가 이미 돌리는 Vitest 경로만 다시 돌려야
한다. 둘 다 아니면 `config/ci/ungated-scripts.json`에 이유와 함께 적는다. 게이트가
닿는 스크립트를 이 목록에 남겨 두면 실패한다. 두 목록에 남은 항목과 이유는 각
파일에 있다.
규모 테스트는 이렇게 나뉜다(리뷰 11-03, `scripts/scale/run-scale-profile.ts`).
- `check:scale:pr`은 merge gate `FE-GATE-005`에서 돈다. 개수·상한·증가 모양만
@@ -48,7 +55,8 @@ Playwright 설정의 `testDir`를 모아 비교한다(`scripts/lib/ungated-tests
- `main`·`nightly`·`release` tier는 CI에서 돌지 않는다. 이 tier들은
`baseline-regression`을 포함한다. 이 단계는 `config/scale/benchmark-baseline.json`을
기록한 CPU 모델에서만 timing을 비교하고, 다른 CPU에서는 `incomplete`로 끝난다.
이 tier에만 있는 테스트 6개는 `ungated-tests.json`에 이유와 함께 남아 있다.
이 tier에만 있는 테스트는 `ungated-tests.json`에, tier를 실행하는 `check:scale:*`
스크립트는 `ungated-scripts.json`에 이유와 함께 남아 있다.
템플릿을 복사해 새 프로젝트를 시작하면 아래 기준선은 템플릿의 값이다. 샘플을
지우거나 구조를 바꾸면 프로젝트 값으로 다시 찍는다.
@@ -308,8 +316,16 @@ stored inside the record.
A runbook drill (`drill:runbook`, FE-GATE-021..025) records each verdict as
`PASS`, `FAIL` or `UNVERIFIED` (`scripts/drill-runbook.ts`, record schema in
`scripts/contracts/release-artifacts.ts`). `PASS`/`FAIL` means the drill checked
it against the local `dist/` build; it reads no `public/` placeholder, so a
missing build fails. Browser boot, live API traffic, smoke after a provider
it against a built `dist/`; it reads no `public/` placeholder, so a missing build
fails. In CI the production stage does not rebuild: `production_gate` downloads
the `promoted-release` artifact of the promotion job, extracts its
`release-candidate.tar.gz` to `.release/promoted-release` after checking it
against the `archive_sha256` of `immutable_build`
(`scripts/verify-ci-candidate-archive.ts`), and each drill command passes
`--release-root .release/promoted-release` (`config/ci/gates.json`). The CI
contract rejects a production drill gate that builds or omits the release root
(`scripts/contracts/ci-gates.ts`, 13-03). Run locally without `--release-root`,
a drill checks the local build. Browser boot, live API traffic, smoke after a provider
switch, and anything the runbook marks as needing provider verification are
`UNVERIFIED`. One `FAIL` makes the drill `FAIL` (exit 1). Otherwise any
`UNVERIFIED` makes it `UNVERIFIED` (exit 3), and the gate is not `PASS`. So
@@ -36,7 +36,7 @@ Measured 2026-09-27, two runs per size, Intel i5-10400F (12 logical CPUs), Node
| 25 | 110 | 3,579,093 | 1.4 GB | 8.1 s / 8.7 s | 1.7 s / 2.1 s | 39 / 274,493 B | 165 / 171,638 B |
| 100 | 410 | 12,157,304 | 4.2 GB | 31.3 s / 43.2 s | 6.0 s / 3.7 s | 114 / 490,658 B | 615 / 704,938 B |
What this means for the declared ceilings (`CONTEXT_MAX_FEATURES = 200`, `src/contexts/reference-context/context-module.ts:10`; `APP_MAX_CONTEXTS = 20`, `src/apps/template-app/app-module.ts:7`):
What this means for the declared ceilings (`CONTEXT_MAX_FEATURES = 200`, `src/contexts/reference-context/context-module.ts:10`; `APP_MAX_CONTEXTS = 20`, `src/apps/template-app/app-module.ts:7`). The table below is a copy of `config/scale/feature-shape-ceilings.json`, which `tests/unit/feature-shape-growth.test.ts` checks against the baseline path and both constants; this document may be deleted after copying the template, the JSON file may not:
| Growth axis | Verified | Condition | Not verified |
| --- | --- | --- | --- |
+23
View File
@@ -31,6 +31,11 @@ import {
ungatedTestFailures,
UNGATED_TESTS_PATH,
} from "./lib/ungated-tests.ts";
import {
parseUngatedScriptExclusions,
ungatedScriptFailures,
UNGATED_SCRIPTS_PATH,
} from "./lib/ungated-scripts.ts";
import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
const contract = await loadCiGateContract(process.cwd());
@@ -92,6 +97,24 @@ try {
failures.push(`ungated test check could not run: ${error instanceof Error ? error.message : String(error)}`);
}
// 12-04: every verification package script is reached by a gate, or
// config/ci/ungated-scripts.json says why not.
try {
const entryScripts = contract.commands.map(({ script }) => script);
failures.push(
...ungatedScriptFailures({
scripts: packageScripts,
entryScripts,
gatedTestPaths: gatedTestPaths(packageScripts, entryScripts, (file) => readFileSync(file, "utf8")),
exclusions: parseUngatedScriptExclusions(
JSON.parse(await readFile(UNGATED_SCRIPTS_PATH, "utf8")),
),
}),
);
} catch (error) {
failures.push(`ungated script check could not run: ${error instanceof Error ? error.message : String(error)}`);
}
const immutable = index.gates.get("FE-GATE-015");
const immutableCommands = immutable?.commandIds.map((id) => index.commands.get(id)?.script);
if (JSON.stringify(immutableCommands) !== JSON.stringify(["build:release-candidate", "verify:local-evidence"])) {
+41 -4
View File
@@ -899,7 +899,7 @@ function validateContractSemantics(
vulnerability_provider: ["provider", ["immutable_build"], "always"],
provenance_provider: ["provider", ["immutable_build"], "always"],
promotion: ["promotion", ["immutable_build", "vulnerability_provider", "provenance_provider"], "needs-success"],
production_gate: ["gate-matrix", ["promotion"], "production"],
production_gate: ["gate-matrix", ["immutable_build", "promotion"], "production"],
field_gate: ["gate-single", ["production_gate"], "field"],
documentation_gate: ["gate-single", [], "documentation"],
};
@@ -916,7 +916,7 @@ function validateContractSemantics(
vulnerability_provider: ["checkout", "setup-node", "frozen-install", "download", "run-provider", "validate-provider-evidence", "upload"],
provenance_provider: ["checkout", "setup-node", "frozen-install", "download", "run-provider", "validate-provider-evidence", "upload"],
promotion: ["checkout", "setup-node", "frozen-install", "download", "download", "download", "verify-promotion", "upload", "cleanup-promotion"],
production_gate: ["checkout", "setup-node", "frozen-install", "run-gate", "upload"],
production_gate: ["checkout", "setup-node", "frozen-install", "download", "extract", "run-gate", "upload"],
field_gate: ["checkout", "setup-node", "frozen-install", "run-gate", "upload"],
documentation_gate: ["checkout", "setup-node", "frozen-install", "run-gate", "upload"],
};
@@ -976,7 +976,12 @@ function validateContractSemantics(
],
// 13-05: FE-GATE-019 probes the promoted release after the provider has
// deployed it, so the live base URL belongs to the production stage.
production_gate: [{ name: "HOSTING_BASE_URL", value: "${{ vars.HOSTING_BASE_URL }}" }],
// 13-03: the drills extract the promoted archive and check it against the
// digest immutable_build recorded.
production_gate: [
{ name: "HOSTING_BASE_URL", value: "${{ vars.HOSTING_BASE_URL }}" },
{ name: "CANDIDATE_ARCHIVE_SHA256", value: "${{ needs.immutable_build.outputs.archive_sha256 }}" },
],
field_gate: [
{ name: "FIELD_WEB_VITALS_INPUT", value: "${{ vars.FIELD_WEB_VITALS_INPUT }}" },
{ name: "MIN_ELIGIBLE_SAMPLES", value: "${{ vars.MIN_ELIGIBLE_SAMPLES }}" },
@@ -1171,6 +1176,38 @@ function validateCanonicalStepFields(
) {
issue("promotion download fields and finalizer/cleanup step identities must remain linked");
}
// 13-03: the production stage drills the promoted archive it downloads. It
// used to rebuild from source, so the drilled bytes were not the release.
const production = contract.jobs.find(({ id }) => id === "production_gate");
const promotedDownload = production?.steps.find(
(step) => step.kind === "download" && step.transferId === "promoted-release",
);
const promotedExtract = production?.steps.find(({ kind }) => kind === "extract");
if (
!production ||
promotedDownload?.kind !== "download" ||
promotedExtract?.kind !== "extract" ||
promotedExtract.archivePath !== `${promotedDownload.path}/release-candidate.tar.gz`
) {
issue("production_gate must download the promoted release and extract its release-candidate.tar.gz");
} else {
for (const gateId of production.gateIds) {
const commands = (contract.gates.find(({ id }) => id === gateId)?.commandIds ?? [])
.map((commandId) => contract.commands.find(({ id }) => id === commandId));
if (!commands.some((command) => command?.script === "drill:runbook")) continue;
if (commands.some((command) => command?.script !== "drill:runbook")) {
issue(`production drill gate must drill the promoted archive only, without rebuilding: ${gateId}`);
}
for (const command of commands) {
const args = command?.args ?? [];
const releaseRoot = args.indexOf("--release-root");
if (releaseRoot < 0 || args[releaseRoot + 1] !== promotedExtract.targetRoot) {
issue(`production drill must pass --release-root ${promotedExtract.targetRoot} (the promoted archive): ${command?.id ?? gateId}`);
}
}
}
}
}
function validateJobStepKinds(
@@ -1178,7 +1215,7 @@ function validateJobStepKinds(
issue: (message: string, path?: PropertyKey[]) => void,
): void {
const allowed: Readonly<Record<z.infer<typeof jobSchema>["kind"], ReadonlySet<string>>> = {
"gate-matrix": new Set(["checkout", "setup-node", "frozen-install", "browser-install", "run-gate", "upload"]),
"gate-matrix": new Set(["checkout", "setup-node", "frozen-install", "browser-install", "download", "extract", "run-gate", "upload"]),
"gate-single": new Set(["checkout", "setup-node", "frozen-install", "run-gate", "upload"]),
immutable: new Set(["checkout", "setup-node", "frozen-install", "run-gate", "archive-candidate", "upload"]),
provider: new Set(["checkout", "setup-node", "frozen-install", "download", "extract", "run-provider", "validate-provider-evidence", "upload"]),
+76
View File
@@ -0,0 +1,76 @@
import { z } from "zod";
import { reachablePackageScripts } from "./package-script-graph.ts";
/**
* 12-04. A verification package script protects nothing unless a CI gate runs
* it. `ungated-tests.ts` covers test files; this covers the scripts. A script
* of a verification family is gated when a gate command reaches it through
* the package script graph, or when it only re-runs Vitest paths a gate
* already runs. Anything else needs a reasoned entry in
* config/ci/ungated-scripts.json.
*/
export const UNGATED_SCRIPTS_PATH = "config/ci/ungated-scripts.json";
const VERIFICATION_SCRIPT = /^(?:check|verify|test|drill|review):/u;
const ungatedScriptsSchema = z
.object({
schemaVersion: z.literal(1),
entries: z.array(
z
.object({
script: z.string().regex(VERIFICATION_SCRIPT),
reason: z.string().trim().min(1, "exclusion reason is required"),
})
.strict(),
),
})
.strict();
export type UngatedScriptExclusion = Readonly<{ script: string; reason: string }>;
export function parseUngatedScriptExclusions(value: unknown): readonly UngatedScriptExclusion[] {
return ungatedScriptsSchema.parse(value).entries;
}
/** Every segment is a Vitest run whose paths all lie inside gated paths. */
function rerunsGatedTests(command: string, gatedTestPaths: readonly string[]): boolean {
const gated = (target: string) =>
gatedTestPaths.some((gatedPath) => target === gatedPath || target.startsWith(`${gatedPath}/`));
return command.split("&&").every((segment) => {
const tokens = segment.trim().split(/\s+/u);
const run = tokens.findIndex(
(token, index) => token === "run" && /(?:run-vitest\.ts|vitest)$/u.test(tokens[index - 1] ?? ""),
);
if (run < 0) return false;
const paths = tokens.slice(run + 1).filter((token) => !token.startsWith("-"));
return paths.length > 0 && paths.every((target) => gated(target.replace(/\/$/u, "")));
});
}
export function ungatedScriptFailures(input: Readonly<{
scripts: Readonly<Record<string, string>>;
entryScripts: readonly string[];
gatedTestPaths: readonly string[];
exclusions: readonly UngatedScriptExclusion[];
}>): string[] {
const reached = new Set(reachablePackageScripts(input.scripts, input.entryScripts));
const gated = (script: string) =>
reached.has(script) || rerunsGatedTests(input.scripts[script] ?? "", input.gatedTestPaths);
const excluded = new Set(input.exclusions.map(({ script }) => script));
const failures = Object.keys(input.scripts)
.filter((script) => VERIFICATION_SCRIPT.test(script) && !gated(script) && !excluded.has(script))
.sort()
.map((script) =>
`verification script is not reached by any CI gate command and is not in ${UNGATED_SCRIPTS_PATH}: ${script}`
);
// An entry for a script a removal deleted is harmless; one for a script a
// gate now reaches would hide the next regression, so it has to go.
for (const { script } of input.exclusions) {
if (input.scripts[script] !== undefined && gated(script)) {
failures.push(`ungated script exclusion is stale; a CI gate reaches it: ${script}`);
}
}
return failures;
}
@@ -29,6 +29,8 @@ import { parseTscExtendedDiagnostics, type TscDiagnostics } from "./collect-tsc-
* `--write` stores the result as config/scale/feature-shape-growth.json.
*/
export const FEATURE_SHAPE_BASELINE_PATH = "config/scale/feature-shape-growth.json";
/** What the declared ceilings rest on, derived by hand from the baseline. */
export const FEATURE_SHAPE_CEILINGS_PATH = "config/scale/feature-shape-ceilings.json";
const SOURCE_FEATURE = "src/features/reference-feature";
const FEATURES_PER_CONTEXT = 200;
+1
View File
@@ -56,6 +56,7 @@ const SAMPLE_EXTRAS: Readonly<Record<string, FeatureExtras>> = Object.freeze({
"tests/unit/feature-shape-growth.test.ts",
"scripts/scale/measure-feature-shape-growth.ts",
"config/scale/feature-shape-growth.json",
"config/scale/feature-shape-ceilings.json",
"tests/mocks",
"tests/fixtures/typecheck/invalid-feature-input.ts",
"tests/fixtures/typecheck/invalid-reference-operation.ts",
@@ -371,12 +371,13 @@ jobs:
production_gate:
name: "\${{ matrix.gate }} / \${{ matrix.name }}"
needs: promotion
needs: [immutable_build, promotion]
if: \${{ gitea.event_name == 'workflow_dispatch' && (inputs.stage == 'production' || inputs.stage == 'field') }}
runs-on: ubuntu-latest
timeout-minutes: 45
env:
HOSTING_BASE_URL: "\${{ vars.HOSTING_BASE_URL }}"
CANDIDATE_ARCHIVE_SHA256: "\${{ needs.immutable_build.outputs.archive_sha256 }}"
strategy:
fail-fast: false
matrix:
@@ -398,6 +399,13 @@ jobs:
run: |
corepack enable
corepack pnpm install --frozen-lockfile --ignore-scripts
- name: Download promoted release
uses: https://github.com/ChristopherHX/gitea-download-artifact@75635f32b4c1c41c4b3d64e8f85210112ed4c9c7
with:
name: "promoted-release-\${{ gitea.run_id }}-\${{ gitea.run_attempt }}"
path: .release/promoted
- name: Verify and extract the candidate through one inode-bound operation
run: node scripts/verify-ci-candidate-archive.ts --archive ".release/promoted/release-candidate.tar.gz" --extract-to ".release/promoted-release"
- name: Run blocking gate
run: corepack pnpm ci:gate -- \${{ matrix.gate }}
- name: Upload production gate evidence
+84 -4
View File
@@ -194,8 +194,8 @@ describe("CI gate contract", () => {
).filter((gateId) => gateId !== "FE-GATE-016"),
);
expect(contract.jobs).toHaveLength(9);
expect(contract.commands).toHaveLength(95);
expect(contract.gates.reduce((total, gate) => total + gate.commandIds.length, 0)).toBe(105);
expect(contract.commands).toHaveLength(98);
expect(contract.gates.reduce((total, gate) => total + gate.commandIds.length, 0)).toBe(103);
expect(contract.commands.filter(({ expect }) => expect === "fail")).toHaveLength(30);
expect(contract.gates.reduce((total, gate) => total + gate.evidenceArtifactIds.length, 0)).toBe(87);
expect(contract.artifacts).toHaveLength(109);
@@ -241,6 +241,83 @@ describe("CI gate contract", () => {
});
});
it("drills the downloaded promoted archive in the production stage without rebuilding (13-03)", async () => {
const contract = await loadCiGateContract(process.cwd());
const index = indexCiGateContract(contract);
const productionGate = contract.jobs.find(({ id }) => id === "production_gate");
const kinds = productionGate?.steps.map(({ kind }) => kind) ?? [];
const download = productionGate?.steps.find((step) => step.kind === "download");
const extract = productionGate?.steps.find((step) => step.kind === "extract");
expect(download).toEqual({
kind: "download",
transferId: "promoted-release",
path: ".release/promoted",
});
expect(extract).toEqual({
kind: "extract",
archivePath: ".release/promoted/release-candidate.tar.gz",
targetRoot: ".release/promoted-release",
});
expect(kinds.indexOf("download")).toBeLessThan(kinds.indexOf("extract"));
expect(kinds.indexOf("extract")).toBeLessThan(kinds.indexOf("run-gate"));
// The extract step checks the archive against the digest immutable_build
// recorded, so the drilled bytes are the promoted candidate.
expect(productionGate?.needs).toContain("immutable_build");
expect(productionGate?.environment).toContainEqual({
name: "CANDIDATE_ARCHIVE_SHA256",
value: "${{ needs.immutable_build.outputs.archive_sha256 }}",
});
for (const gateId of ["FE-GATE-021", "FE-GATE-022", "FE-GATE-023", "FE-GATE-024", "FE-GATE-025"]) {
const commands = index.gates.get(gateId)?.commandIds.map((id) => index.commands.get(id)!) ?? [];
expect(commands.map(({ script }) => script), gateId).toEqual(["drill:runbook"]);
const args = commands[0]?.args ?? [];
expect(args[args.indexOf("--release-root") + 1], gateId).toBe(".release/promoted-release");
}
const workflow = renderCiWorkflow(contract);
const productionJob = workflow.slice(
workflow.indexOf(" production_gate:\n"),
workflow.indexOf(" field_gate:\n"),
);
const downloadAt = productionJob.indexOf("- name: Download promoted release");
const extractAt = productionJob.indexOf(
'--archive ".release/promoted/release-candidate.tar.gz" --extract-to ".release/promoted-release"',
);
expect(downloadAt).toBeGreaterThan(0);
expect(extractAt).toBeGreaterThan(downloadAt);
expect(productionJob.indexOf("Run blocking gate")).toBeGreaterThan(extractAt);
});
it.each([
[
"a drill without --release-root",
(contract: Record<string, any>) => {
const drill = contract.commands.find((command: Record<string, any>) => command.id === "drill-runbook");
drill.args = ["--", "FE-RB-005"];
},
],
[
"a drill gate that rebuilds from source",
(contract: Record<string, any>) => {
const gate = contract.gates.find((candidate: Record<string, any>) => candidate.id === "FE-GATE-025");
gate.commandIds = ["build", ...gate.commandIds];
},
],
[
"a production stage without the promoted archive",
(contract: Record<string, any>) => {
const job = contract.jobs.find((candidate: Record<string, any>) => candidate.id === "production_gate");
job.steps = job.steps.filter((step: Record<string, any>) => !["download", "extract"].includes(step.kind));
},
],
])("rejects %s in the production stage (13-03)", async (_name, mutate) => {
const contract = JSON.parse(
JSON.stringify(await loadCiGateContract(process.cwd())),
) as Record<string, any>;
mutate(contract);
expect(() => parseCiGateContract(contract)).toThrow(/promoted/iu);
});
it("keeps the action registry recursively immutable and resolves only known actions", () => {
expect(Object.isFrozen(CI_ACTION_REGISTRY)).toBe(true);
expect(Object.values(CI_ACTION_REGISTRY).every((action) => Object.isFrozen(action))).toBe(true);
@@ -1406,7 +1483,10 @@ describe("CI workflow generation", () => {
).toHaveLength(9);
expect(first).not.toMatch(/corepack pnpm install --frozen-lockfile$/mu);
expect(first).toContain("verify-ci-candidate-archive.ts --archive");
expect(first).not.toContain("--extract-to");
// Providers and promotion read the archive without extracting it; only the
// production drills extract the promoted archive (13-03).
expect(first.match(/--extract-to/gu)).toHaveLength(1);
expect(first.indexOf("--extract-to")).toBeGreaterThan(first.indexOf(" production_gate:\n"));
expect(first).not.toMatch(/\btar\s+[^\n]*--extract/u);
expect(first).toContain("node scripts/stage-verified-promotion.ts");
expect(first).toContain("outputs:\n invocation_nonce: ${{ steps.supervise_vulnerability.outputs.invocation_nonce }}");
@@ -1436,7 +1516,7 @@ describe("CI workflow generation", () => {
'if [ -n "$PROMOTION_STAGING_ROOT" ] && [ -n "$PROMOTION_CLEANUP_TOKEN" ] && [ -n "$PROMOTION_RUNNER_TEMP_DEV" ] && [ -n "$PROMOTION_RUNNER_TEMP_INO" ] && [ -n "$PROMOTION_STAGING_DEV" ] && [ -n "$PROMOTION_STAGING_INO" ]; then',
);
const actionUses = [...first.matchAll(/^\s+-?\s*uses: (.+)$/gmu)].map((match) => match[1]);
expect(actionUses).toHaveLength(32);
expect(actionUses).toHaveLength(33);
expect(new Set(actionUses)).toEqual(
new Set([
"https://github.com/actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5",
@@ -0,0 +1,65 @@
import { readdir, readFile } from "node:fs/promises";
import path from "node:path";
import { describe, expect, it } from "vitest";
/**
* README.md, "Files you can delete after copying", tells a new project that
* the build and the gates read none of the history documents except
* `docs/reviews/adapters/INVENTORY.md`. The removal fixtures rely on the same
* promise: they do not copy `docs/`. A test that opens a review document broke
* all three removal checks (fix of 11-04), so the promise is checked here.
*/
const CODE_ROOTS = ["src", "tests", "scripts", "config", "recipes", "schemas", ".gitea"];
const ROOT_FILES = [
"package.json",
"vite.config.ts",
"vitest.config.ts",
"eslint.config.ts",
"playwright.config.ts",
];
// Built from pieces so that this file does not match itself.
const REVIEWS = ["docs", "reviews", ""].join("/");
const KEPT = `${REVIEWS}adapters/INVENTORY.md`;
const DELETABLE = [
new RegExp(`${REVIEWS}(?!adapters/INVENTORY\\.md)`, "u"),
new RegExp(["docs", "superpowers"].join("/"), "u"),
new RegExp(`\\b${"SPEC"}\\.md\\b`, "u"),
new RegExp(`\\b${"CLAUDE"}\\.md\\b`, "u"),
new RegExp(`(^|["'\`(\\s])${"tasks"}/`, "u"),
];
async function codeFiles(directory: string): Promise<string[]> {
const entries = await readdir(directory, { withFileTypes: true }).catch(
() => [],
);
const files = await Promise.all(
entries.map(async (entry) => {
const target = path.join(directory, entry.name);
if (entry.isDirectory())
return entry.name === "node_modules" ? [] : codeFiles(target);
return /\.(?:[cm]?[jt]sx?|json|ya?ml)$/u.test(entry.name) ? [target] : [];
}),
);
return files.flat();
}
describe("deletable history documents", () => {
it("are read by no code, test, script or configuration", async () => {
const files = [
...(await Promise.all(CODE_ROOTS.map(codeFiles))).flat(),
...ROOT_FILES,
];
const readers: string[] = [];
for (const file of files) {
const lines = (await readFile(file, "utf8").catch(() => "")).split("\n");
lines.forEach((line, index) => {
if (DELETABLE.some((pattern) => pattern.test(line)))
readers.push(`${file}:${index + 1}`);
});
}
expect(readers, `only ${KEPT} may be read`).toEqual([]);
});
});
+31 -6
View File
@@ -4,8 +4,11 @@ import { describe, expect, it } from "vitest";
import {
FEATURE_SHAPE_BASELINE_PATH,
FEATURE_SHAPE_CEILINGS_PATH,
renameReferenceFeature,
} from "../../scripts/scale/measure-feature-shape-growth.ts";
import { APP_MAX_CONTEXTS } from "../../src/apps/template-app/app-module.ts";
import { CONTEXT_MAX_FEATURES } from "../../src/contexts/reference-context/context-module.ts";
/**
* 11-04 (D-18). The scale evidence used to come from stub features that only
@@ -92,12 +95,34 @@ describe("feature-shape growth measurement (11-04)", () => {
}
});
it("states in the acceptance matrix what the ceilings rest on", async () => {
const acceptance = await readFile(
"docs/reviews/2026-09-23-extreme-scale-acceptance.md",
"utf8",
it("states in the committed rationale what the ceilings rest on", async () => {
// The rationale lives next to the baseline, not in a review document: the
// history documents may be deleted after copying (README.md).
const rationale = JSON.parse(
await readFile(FEATURE_SHAPE_CEILINGS_PATH, "utf8"),
) as Readonly<{
baseline: string;
ceilings: Readonly<{ contextMaxFeatures: number; appMaxContexts: number }>;
axes: readonly Readonly<Record<string, string>>[];
}>;
expect(rationale.baseline).toBe(FEATURE_SHAPE_BASELINE_PATH);
expect(rationale.ceilings).toEqual({
contextMaxFeatures: CONTEXT_MAX_FEATURES,
appMaxContexts: APP_MAX_CONTEXTS,
});
expect(rationale.axes.map((row) => row.axis)).toEqual(
expect.arrayContaining([
"Typecheck of one app",
"Production build",
"Initial JavaScript",
"Lazy JavaScript",
"Routes",
]),
);
expect(acceptance).toContain(FEATURE_SHAPE_BASELINE_PATH);
expect(acceptance).toMatch(/\| Growth axis \| Verified \| Condition \| Not verified \|/u);
for (const row of rationale.axes) {
for (const column of ["axis", "verified", "condition", "notVerified"])
expect(row[column], `${row.axis}.${column}`).toMatch(/\S/u);
}
});
});
+103
View File
@@ -0,0 +1,103 @@
import { readFileSync } from "node:fs";
import { readFile } from "node:fs/promises";
import { describe, expect, it } from "vitest";
import { loadCiGateContract } from "../../scripts/contracts/ci-gates.ts";
import {
parseUngatedScriptExclusions,
ungatedScriptFailures,
UNGATED_SCRIPTS_PATH,
} from "../../scripts/lib/ungated-scripts.ts";
import { gatedTestPaths } from "../../scripts/lib/ungated-tests.ts";
/**
* 12-04. Test files had an orphan check; package scripts did not. A `check:*`
* script that no gate reaches (check:remediation-ledger, and the checks only
* verify:extreme-scale ran) could break without anyone noticing.
*/
async function repositoryInputs() {
const contract = await loadCiGateContract(process.cwd());
const packageDocument = JSON.parse(await readFile("package.json", "utf8")) as {
scripts: Record<string, string>;
};
const entryScripts = contract.commands.map(({ script }) => script);
return {
scripts: packageDocument.scripts,
entryScripts,
gatedTestPaths: gatedTestPaths(packageDocument.scripts, entryScripts, (file) =>
readFileSync(file, "utf8"),
),
exclusions: parseUngatedScriptExclusions(
JSON.parse(await readFile(UNGATED_SCRIPTS_PATH, "utf8")),
),
};
}
const fixture = {
scripts: {
gate: "corepack pnpm check:wired && node scripts/run-vitest.ts run tests/unit",
"check:wired": "node scripts/wired.ts",
"check:orphan": "node scripts/orphan.ts",
"check:subset": "node scripts/run-vitest.ts run tests/unit/one.test.ts --reporter=default",
"check:outside": "node scripts/run-vitest.ts run tests/scale/heavy.test.ts",
"lint:fix": "eslint . --fix",
},
entryScripts: ["gate"],
gatedTestPaths: ["tests/unit"],
exclusions: [],
};
describe("ungated verification scripts", () => {
it("reaches every verification script from a CI gate or names why not", async () => {
expect(ungatedScriptFailures(await repositoryInputs())).toEqual([]);
});
it.each(["check:request-fanout", "check:app-build-input", "check:app-build-input:bundle"])(
"gates %s",
async (script) => {
const inputs = await repositoryInputs();
expect(inputs.exclusions.some((entry) => entry.script === script)).toBe(false);
expect(
ungatedScriptFailures({ ...inputs, scripts: { ...inputs.scripts }, exclusions: [] }),
).not.toContainEqual(expect.stringContaining(`: ${script}`));
},
);
it("rejects a check script that no gate reaches", () => {
expect(ungatedScriptFailures(fixture)).toEqual([
`verification script is not reached by any CI gate command and is not in ${UNGATED_SCRIPTS_PATH}: check:orphan`,
`verification script is not reached by any CI gate command and is not in ${UNGATED_SCRIPTS_PATH}: check:outside`,
]);
});
it("counts a Vitest subset as gated only when a gate runs every path", () => {
const failures = ungatedScriptFailures(fixture);
expect(failures.join("\n")).not.toContain("check:subset");
expect(failures.join("\n")).toContain("check:outside");
});
it("accepts a reasoned exclusion and rejects a stale one", () => {
expect(
ungatedScriptFailures({
...fixture,
exclusions: [
{ script: "check:orphan", reason: "local only" },
{ script: "check:outside", reason: "heavy" },
{ script: "check:wired", reason: "stale" },
// A removal may delete the script; its entry is harmless.
{ script: "check:removed", reason: "gone" },
],
}),
).toEqual([`ungated script exclusion is stale; a CI gate reaches it: check:wired`]);
});
it("requires a reason for every exclusion", () => {
expect(() =>
parseUngatedScriptExclusions({
schemaVersion: 1,
entries: [{ script: "check:orphan", reason: " " }],
}),
).toThrow(/reason/u);
});
});