Skip to content
This repository was archived by the owner on Nov 4, 2026. It is now read-only.

Commit da7c3d9

Browse files
docs(guide): point ci-cd-pipeline.md's populations at what derives them (#9005)
Three sentences stated a live population as a literal with nothing deriving it: the docs-page population the eager-closure section credits to the /docs/[[...slug]] route, the file population the shell-escape section credits to the `skills` scan root, and the sweeper's page window, copied out of a source constant. The first was already false - it claimed 181 against a corpus of 184 git-tracked .md/.mdx files under the directory apps/site/source.config.ts declares - and nothing in CI could go red over any of the three. Each sentence now names the tree the population is derived from and the run that prints the live reading, and ci-cd-pipeline-doc.test.ts refuses a count written back into any of the three sections. The numbers are NOT corrected: a corrected count with nothing checking it is the same card a month later, which is the ruling objectui#7448, objectui#7825 and objectui#7965 each recorded after doing exactly that. The assertions judge JOINED text. Both defective sentences wrapped - the numeral ended one line and its noun began the next - so a per-line reader returns zero for sentences that are plainly present, measured twice: by the seat verifying this card and by objectui#8606 from the workflow-header side. The pin proves its own unit by finding a phrase this page carries that no single line contains, and both halves of that control are asserted so "clean" can never mean "unreadable". Four neighbouring sentences that state the commit or window they were measured on are deliberately untouched: those declare their measurement, which is the remedy rather than the defect. Refs: objectui#8629 Co-authored-by: Claude Co-authored-by: 包周涛 <baozhoutao@hotoa.com>
1 parent 2596b1b commit da7c3d9

3 files changed

Lines changed: 262 additions & 13 deletions

File tree

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
---
3+
4+
Documentation and test-only change — this publishes nothing, declared explicitly with an empty
5+
frontmatter rather than left undeclared. No package `src/` is touched: the diff is
6+
`content/docs/guide/ci-cd-pipeline.md` plus new assertions in the test that already owns that page.
7+
8+
Three sentences on the CI/CD guide stated a live population as a literal with nothing deriving it:
9+
the docs-page population the eager-closure section credits to the `/docs/[[...slug]]` route, the
10+
file population the shell-escape section credits to the `skills` scan root, and the sweeper's page
11+
window, copied out of a source constant. The first was measurably false — it claimed 181 against a
12+
corpus of 184 git-tracked `.md`/`.mdx` files under the directory `apps/site/source.config.ts`
13+
declares — and nothing in CI could go red over any of the three.
14+
15+
Each sentence now names the tree its population is derived from and the run that prints the live
16+
reading (the eager-closure gate's `gauge:` line, the residue gate's per-root `N file(s), N fence(s)`
17+
line, and `CLOSED_ISSUE_WINDOW_PAGES` in the sweeper), and `ci-cd-pipeline-doc.test.ts` refuses a
18+
count written back into any of the three sections. The numbers were not corrected: a corrected count
19+
with nothing checking it is the same drift a month later.
20+
21+
The assertions read the page as JOINED text, because both defective sentences wrapped — the numeral
22+
ended one line and its noun began the next, so a per-line reader returns zero for sentences that are
23+
plainly present. The pin proves its own unit by finding a phrase this page carries that no single
24+
line contains.
25+
26+
Four neighbouring sentences that state the commit or window they were measured on are deliberately
27+
untouched: those declare their measurement, which is the remedy rather than the defect. A fifth
28+
figure on the same page states its population with a hyphen, which the family's noun pattern does
29+
not match; it is recorded in the pin's own comment and filed as objectui#9004 rather than fixed
30+
here, because the same figure is mirrored outside `content/docs/**`.

‎content/docs/guide/ci-cd-pipeline.md‎

Lines changed: 29 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1348,14 +1348,22 @@ a **fenced code block** contains one of the enumerated machine-produced shell-qu
13481348

13491349
The contributor tree `.claude/skills/` joined that list in
13501350
[#7403](https://github.com/objectstack-ai/objectui/issues/7403). It is not published, but it is
1351-
agent-**written** and agent-**read**, which is both halves of the mechanism this gate exists for — and
1352-
[#7251](https://github.com/objectstack-ai/objectui/issues/7251) had moved two contributor guides there
1353-
out of `skills/objectui/`, taking 18 fenced blocks off the surface in one commit with nothing turning
1354-
red. Nothing could have turned red: the `skills` row's file floor is a **collapse** detector, and 16
1355-
files stayed behind to satisfy it while the two that left went unmeasured. A floor measures the roots
1356-
that are declared, never the tree that walked out of them, so a move and its `SCAN_ROOTS` row belong
1357-
in one change. The sibling gate `check-skills-paths` lost 55 stated paths to the same move and was
1358-
widened the same way in [#7358](https://github.com/objectstack-ai/objectui/issues/7358).
1351+
agent-**written** and agent-**read**, which is both halves of the mechanism this gate exists for —
1352+
and [#7251](https://github.com/objectstack-ai/objectui/issues/7251) had moved two contributor guides
1353+
there out of `skills/objectui/`, taking 18 fenced blocks off the surface in one commit with nothing
1354+
turning red. Nothing could have turned red: the `skills` row's file floor is a **collapse**
1355+
detector, and the files that stayed behind were enough to satisfy it while the two that left went
1356+
unmeasured. A floor measures the roots that are declared, never the tree that walked out of them, so
1357+
a move and its `SCAN_ROOTS` row belong in one change. ⛔ How many stayed is not stated here,
1358+
deliberately: this sentence used to carry that as a literal, the tree moved under it, and nothing
1359+
went red over that distance, because nothing fails on a number written in prose
1360+
([#8629](https://github.com/objectstack-ai/objectui/issues/8629),
1361+
[#7448](https://github.com/objectstack-ai/objectui/issues/7448)). The gate derives every root's
1362+
population from `SCAN_ROOTS` on each run and prints it — its result line carries a per-root `N
1363+
file(s), N fence(s)` reading — so running `scripts/check-shell-escape-residue.mjs` is the live
1364+
answer to what the `skills` root holds today. The sibling gate `check-skills-paths` lost 55 stated
1365+
paths to the same move and was widened the same way in
1366+
[#7358](https://github.com/objectstack-ai/objectui/issues/7358).
13591367

13601368
**Why it needed a gate.** In [#5150](https://github.com/objectstack-ai/objectui/issues/5150) the
13611369
`git commit -F -` example in `AGENTS.md` §9 shipped with its heredoc terminator wrapped in the
@@ -1488,9 +1496,15 @@ one `node` call over the source tree, **no install and no build**, ~1.3 s.
14881496

14891497
**What it weighs, and what was not weighing it.**
14901498
`apps/site/app/components/registerCatalogBlocks.ts` is a list of side-effect imports, and each one
1491-
pulls its package's module graph into the Next docs route `/docs/[[...slug]]` — a route **all 181
1492-
docs pages share**, not just the catalog gallery. The cards that added to that list said the cost
1493-
was governed by `check:eager-closure`. It was not:
1499+
pulls its package's module graph into the Next docs route `/docs/[[...slug]]` — a route **every docs
1500+
page shares**, not just the catalog gallery. ⛔ No page count here, deliberately: this sentence used
1501+
to state one as a literal, it went stale, and nothing went red over that distance, because nothing
1502+
fails on a number written in prose ([#8629](https://github.com/objectstack-ai/objectui/issues/8629),
1503+
[#7448](https://github.com/objectstack-ai/objectui/issues/7448)). That population is derived on
1504+
every run from the directory `apps/site/source.config.ts` declares as the docs collection —
1505+
`content/docs` — and this gate prints how much of it the walk reached: the `gauge:` line reports the
1506+
route roots it crawled and how many of those are compiled MDX modules out of that directory. The
1507+
cards that added to that list said the cost was governed by `check:eager-closure`. It was not:
14941508
`scripts/check-eager-closure-budget.mjs` reads `apps/console/dist/eager-closure.json` and
14951509
`performance-budget.yml` builds `@object-ui/console`, so that budget weighs the **console**. The
14961510
only measurement of the docs route that has ever existed was reconstructed by hand, once, from the
@@ -2334,8 +2348,10 @@ and is meant to stay re-syncable, so this install keeps its differences in one p
23342348
sweeper's closed-card reader (`pm:*` labels left on cards that already closed) is *called* here: the
23352349
reader is **on**, with a dated floor. The sweep step sets `PM_SWEEP_CLOSED_FLOOR: '2026-08-28'`, so
23362350
only cards closed on or after that cutover are judged, and the page window is deliberately left
2337-
unset — back to the sweeper's own upstream default of 4 pages. The floor, not a zeroed window, is
2338-
what holds the historical carriers out.
2351+
unset — back to the sweeper's own upstream default, which `scripts/pm/check-half-states.mjs` exports
2352+
as `CLOSED_ISSUE_WINDOW_PAGES` rather than being restated here, a constant copied into prose being a
2353+
number that rots the moment the export moves. The floor, not a zeroed window, is what holds the
2354+
historical carriers out.
23392355

23402356
**Why a floor rather than a plain "on".** Stripping `pm:*` on close only became this repo's practice
23412357
on the cutover date, and the measurement taken just before it says what an unfloored reader would do

‎scripts/__tests__/ci-cd-pipeline-doc.test.ts‎

Lines changed: 203 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2706,3 +2706,206 @@ describe('ci-cd-pipeline.md — the four sections measured as parity defects', (
27062706
});
27072707
});
27082708
});
2709+
2710+
/**
2711+
* objectui#8629: three live populations on this page were written down as literals
2712+
* with nothing deriving them — the docs-page population the eager-closure section
2713+
* credits to the route, the file population the shell-escape section credits to the
2714+
* `skills` scan root, and the sweeper's page window, copied out of a source
2715+
* constant. The first was already false when the card was filed. ⛔ Correcting the
2716+
* numerals would have been the same card again in a month, which is the ruling
2717+
* objectui#7448, objectui#7825 and objectui#7965 have each recorded after doing
2718+
* exactly that; the page now names the tree each population is derived from and the
2719+
* run that prints it, and these pins refuse a count written back.
2720+
*
2721+
* ## ⭐ The unit, which is the transferable half
2722+
*
2723+
* Both defective sentences WRAP: the numeral sat at the end of one line and its noun
2724+
* at the start of the next. A per-line reader returns **zero** for each of them on a
2725+
* file where they are plainly present — measured, not theorised, twice: by the seat
2726+
* that verified this card and by objectui#8606 from the workflow-header side. So
2727+
* every assertion below judges JOINED text, and the first test proves the unit is
2728+
* really joined by finding a phrase this page carries that no single line contains.
2729+
*
2730+
* ## Why these are section-scoped and not page-wide
2731+
*
2732+
* ⛔ A page-wide ban on "N files" would flag the sentences that are CORRECT — the
2733+
* skills-paths measurement and the test-file cell each state the commit they were
2734+
* measured on, the changeset-overwrite figure states its window. Those declare what
2735+
* they measured, which is the remedy, not the defect; rewriting them into live
2736+
* figures would create the defect. The scope of each pin is therefore the one
2737+
* section whose sentence was stating a population it did not derive.
2738+
*
2739+
* ⚠️ Known gap, recorded rather than papered over: the family's noun pattern needs
2740+
* whitespace before the noun, so a hyphenated population ("a 556-page docs build",
2741+
* which this page also carries and which is mirrored in the gate's own header) is
2742+
* invisible to it. That instance is filed as objectui#9004; widening the noun
2743+
* pattern is not a change this pin may make alone, because the same pattern is
2744+
* shared with the other carriers of the family.
2745+
*/
2746+
describe('ci-cd-pipeline.md — populations are pointed at, never counted in prose', () => {
2747+
const EAGER_HEADING = '## Docs Route Eager Closure (`docs-route-eager-closure.yml`)';
2748+
const RESIDUE_HEADING = '## Shell Escape Residue (`shell-escape-residue.yml`)';
2749+
const PATROL_HEADING = '### Half-State Patrol (`half-state-patrol.yml`)';
2750+
2751+
/** A section of the page as one line — the unit every assertion here judges. */
2752+
const flat = (heading: string): string => section(heading).replace(/\s+/g, ' ').trim();
2753+
2754+
/** `<number> <noun>`, the family's own shape, applied to joined text. */
2755+
const population = (noun: string): RegExp =>
2756+
new RegExp(
2757+
String.raw`\b(?:\d+|one|two|three|four|five|six|seven|eight|nine|ten|eleven|twelve)\s+${noun}\b`,
2758+
'i',
2759+
);
2760+
2761+
it('judges joined text — a per-line reader cannot see these sentences at all', () => {
2762+
// The control is built from the page rather than hard-coded, so a re-wrap moves
2763+
// it instead of breaking it: three consecutive words that straddle a line break
2764+
// and appear on no single line. If this page ever stops wrapping its prose the
2765+
// control goes undefined and says so, rather than passing on a reader that has
2766+
// quietly become per-line-equivalent.
2767+
const lines = doc.split('\n');
2768+
const joined = doc.replace(/\s+/g, ' ');
2769+
let control: string | undefined;
2770+
for (let i = 0; i < lines.length - 1; i += 1) {
2771+
const before = lines[i].trim().split(/\s+/);
2772+
const after = lines[i + 1].trim().split(/\s+/);
2773+
if (before.length < 3 || after.length < 3) continue;
2774+
const candidate = `${before[before.length - 2]} ${before[before.length - 1]} ${after[0]}`;
2775+
if (!/^[\w'’,.—-]+ [\w'’,.—-]+ [\w'’,.—-]+$/.test(candidate)) continue;
2776+
if (!joined.includes(candidate)) continue;
2777+
if (lines.some((line) => line.includes(candidate))) continue;
2778+
control = candidate;
2779+
break;
2780+
}
2781+
expect(
2782+
control,
2783+
'no phrase on this page straddles a line break any more, so the joined-text unit below is ' +
2784+
'no longer demonstrably stronger than a per-line one. Check how the page is wrapped ' +
2785+
'before trusting any zero from the assertions in this block.',
2786+
).toBeDefined();
2787+
2788+
// Both halves asserted, so "clean" can never mean "unreadable": the phrase IS in
2789+
// the joined text and is NOT in any line. That gap is exactly the one that hid
2790+
// two of this card's three defects from the census that went looking for them.
2791+
expect(joined).toContain(control!);
2792+
expect(lines.filter((line) => line.includes(control!))).toEqual([]);
2793+
});
2794+
2795+
it('states no docs-page population, and names what derives it instead', () => {
2796+
const sec = flat(EAGER_HEADING);
2797+
2798+
// Positive controls first: an assertion that the section does not contain a count
2799+
// is vacuously green on a section that moved or emptied.
2800+
for (const anchor of [
2801+
'registerCatalogBlocks.ts',
2802+
'apps/site/source.config.ts',
2803+
'`content/docs`',
2804+
'`gauge:`',
2805+
]) {
2806+
expect(
2807+
sec,
2808+
`the Docs Route Eager Closure section no longer names ${anchor}. That is the pointer this ` +
2809+
'card put in place of the count, so re-point it (or the negative assertion below is ' +
2810+
'guarding nothing).',
2811+
).toContain(anchor);
2812+
}
2813+
2814+
// Parity: the two things the page now points at have to be real, or the pointer is
2815+
// just a different kind of unchecked prose.
2816+
const sourceConfig = fs.readFileSync(path.join(repoRoot, 'apps/site/source.config.ts'), 'utf8');
2817+
expect(
2818+
sourceConfig,
2819+
"apps/site/source.config.ts no longer declares `dir: '../../content/docs'`. The page tells " +
2820+
'readers the docs-page population is derived from the directory this file declares — ' +
2821+
'say where it is derived from now.',
2822+
).toMatch(/dir:\s*'\.\.\/\.\.\/content\/docs'/);
2823+
const gate = fs.readFileSync(
2824+
path.join(repoRoot, 'scripts/check-docs-route-eager-closure.mjs'),
2825+
'utf8',
2826+
);
2827+
expect(
2828+
gate,
2829+
'scripts/check-docs-route-eager-closure.mjs no longer prints a `gauge:` line naming the ' +
2830+
'route roots it crawled. The page points at that line as the live reading, so either the ' +
2831+
'line comes back or the page must point somewhere else.',
2832+
).toMatch(/gauge: \$\{[^}]+\} modules crawled from \$\{[^}]+\} route roots/);
2833+
2834+
const counted = sec.match(population('(?:docs\\s+)?pages?'));
2835+
expect(
2836+
counted?.[0],
2837+
`the Docs Route Eager Closure section states a docs-page population again (found ` +
2838+
`"${counted?.[0]}"). ⛔ That is the defect this card removed, not a stale number to ` +
2839+
`refresh: "all 181 docs pages" was false against a corpus of 184 git-tracked .md/.mdx ` +
2840+
`files and nothing could go red over it. The population is derived from the docs ` +
2841+
`collection directory on every run — name the directory and the reading, never the number.`,
2842+
).toBeUndefined();
2843+
});
2844+
2845+
it('states no `skills` file population, and points at the per-root reading', () => {
2846+
const sec = flat(RESIDUE_HEADING);
2847+
2848+
for (const anchor of ['`SCAN_ROOTS`', 'scripts/check-shell-escape-residue.mjs', 'file(s)']) {
2849+
expect(
2850+
sec,
2851+
`the Shell Escape Residue section no longer names ${anchor} — the negative assertion ` +
2852+
'below needs that pointer present to be guarding anything.',
2853+
).toContain(anchor);
2854+
}
2855+
2856+
// Parity: the gate really does print a per-root reading in the shape the page
2857+
// quotes. Without this, the page could point at a reading that no longer exists.
2858+
const gate = fs.readFileSync(path.join(repoRoot, 'scripts/check-shell-escape-residue.mjs'), 'utf8');
2859+
for (const [pattern, what] of [
2860+
[/file\(s\)/, 'a per-root `N file(s)` figure'],
2861+
[/fence\(s\)/, 'a per-root `N fence(s)` figure'],
2862+
] as const) {
2863+
expect(
2864+
gate,
2865+
`scripts/check-shell-escape-residue.mjs no longer prints ${what}. The page sends readers ` +
2866+
'to that run for what the `skills` root holds, so the reading has to survive or the ' +
2867+
'page has to be re-pointed.',
2868+
).toMatch(pattern);
2869+
}
2870+
2871+
const counted = sec.match(population('files?'));
2872+
expect(
2873+
counted?.[0],
2874+
`the Shell Escape Residue section states a file population again (found "${counted?.[0]}"). ` +
2875+
'⛔ A live count of what the `skills` scan root holds, written where nothing derives it, ' +
2876+
'is what this card removed. The gate prints that figure per root on every run — point at ' +
2877+
'the run, never at a numeral.',
2878+
).toBeUndefined();
2879+
});
2880+
2881+
it('copies no page window out of the sweeper, and names the export instead', () => {
2882+
const sec = flat(PATROL_HEADING);
2883+
2884+
// ⚠️ This pin decides nothing about whether a `pages?` noun that means *paginated
2885+
// API result pages* belongs to objectui#7448's family at all — that question is
2886+
// objectui#7966's and it is open. It holds only the local fact: a constant copied
2887+
// into prose rots when the export moves, whichever way the noun set is ruled.
2888+
expect(
2889+
sec,
2890+
'the Half-State Patrol section no longer names `CLOSED_ISSUE_WINDOW_PAGES`. That name is ' +
2891+
'what replaced the copied value, so restore the pointer rather than the number.',
2892+
).toContain('`CLOSED_ISSUE_WINDOW_PAGES`');
2893+
2894+
const sweeper = fs.readFileSync(path.join(repoRoot, 'scripts/pm/check-half-states.mjs'), 'utf8');
2895+
const literal = /^export const CLOSED_ISSUE_WINDOW_PAGES = (\d+);$/m.exec(sweeper)?.[1];
2896+
expect(
2897+
literal,
2898+
'`CLOSED_ISSUE_WINDOW_PAGES` is no longer a plain literal export of ' +
2899+
'scripts/pm/check-half-states.mjs, so this test can no longer tell whether the page ' +
2900+
'restates it. Re-point the extraction before trusting the green below.',
2901+
).toBeDefined();
2902+
2903+
const counted = sec.match(population('pages?'));
2904+
expect(
2905+
counted?.[0],
2906+
`the Half-State Patrol section states a page window again (found "${counted?.[0]}"). The ` +
2907+
`sweeper exports it as CLOSED_ISSUE_WINDOW_PAGES (${literal} today) — naming the export ` +
2908+
`survives the value moving, a copy of the value does not.`,
2909+
).toBeUndefined();
2910+
});
2911+
});

0 commit comments

Comments
 (0)