Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
fix(docs): keep evergreen review deadlines out of the build gate
jkomyno committed
Nov 10, 2026 at 15:43 UTC
2a81e88afd8207ec04647ffd48b1f39509ad37eb
5 files changed
+42
-17
docs/decisions/kb-freshness-verification.md
+15
-7
@@ -14,6 +14,12 @@ Findings never block the data sync. They are written to the job summary and to a
14
single long-lived `kb-freshness` issue, which the job closes when the KB verifies
15
clean.
16
17
+An evergreen guide's review deadline is a maintenance reminder: expiry remains
18
+an error in this report, but does not block catalog assembly or unpublish the
19
+guide. A published time-sensitive guide with an expired review window still
20
+blocks catalog assembly until it is reverified or explicitly held for review.
21
+Both kinds of published guide must carry valid verification and review dates.
22
+
23
## Context
24
25
The KB carries two kinds of claim. Most are mechanically checkable — a tool slug
@@ -26,11 +32,12 @@ the human queue fills with work that did not need a human. An audit of the sourc
32
corpus found 36 of 180 cited action identifiers already absent from the catalog;
33
this check found one of them — `CANVAS_GET_ACCOUNTS` — live in a published guide.
34
29
-Review dates also fail late. `reviewAfter` expiry throws during catalog assembly,
30
-so an expired guide breaks the docs build rather than quietly unpublishing. At
31
-the time of writing, 22 of 27 published guides share a single `reviewAfter` date,
32
-so they expire together and the cheapest response on that day is to bump the
33
-dates rather than re-verify. The verifier reports that cohort as a finding.
35
+Review dates used to fail late. Every `reviewAfter` expiry threw during catalog
36
+assembly, so one overdue evergreen guide broke the docs build. On 2026-11-10,
37
+61 evergreen guides expired together and blocked unrelated SDK pull requests
38
+during docs installation. Evergreen deadlines now stay in the verifier report;
39
+time-sensitive expiry still blocks publication. The verifier also reports
40
+guides sharing a review date so the maintenance queue is visible before expiry.
41
42
## What Is Checked
43
@@ -91,8 +98,9 @@ asserts no published guide renders from the source snapshot.
98
- Human review narrows to prose that cannot be checked mechanically.
99
- A guide contradicting production is visible within hours, in one tracked issue
100
that closes itself.
94
-- The checker must keep working when the build gate has tripped, so it assembles
95
- the catalog with a floor date and re-checks expiry against the real clock.
101
+- The checker must keep working when time-sensitive expiry has tripped the build
102
+ gate, so it assembles the catalog with a floor date and re-checks all review
103
+ deadlines against the real clock.
104
- Coverage — questions with no article at all — is out of scope here. That is a
105
demand-side signal and is measured from support ticket volume, not from the
106
catalog.
docs/decisions/public-knowledge-base.md
+5
-2
@@ -59,9 +59,12 @@
59
canonical routes, verification dates, review deadlines, and publication
60
state.
61
- Publication rejects content that is not explicitly public, contains known
62
- private-data markers, is stale, has broken references, or conflicts with an
63
- existing route.
62
+ private-data markers, has expired time-sensitive verification, has broken
63
+ references, or conflicts with an existing route.
64
- Time-sensitive content stays unpublished until it has been reverified.
65
+- Evergreen review deadlines remain freshness-check errors for follow-up, but
66
+ do not block the docs build or remove previously reviewed guides. Dates are
67
+ extended only after review.
68
- The running docs application reads only the checked-in public snapshot; it
69
does not access the source repository at runtime.
70
docs/lib/kb/catalog.ts
+1
-1
@@ -135,7 +135,7 @@ export function buildKbCatalog(
135
if (!reviewAfter) {
136
throw new Error(`${definition.slug}: published content requires reviewAfter`);
137
}
138
- if (reviewAfter.valueOf() <= now.valueOf()) {
138
+ if (definition.freshness === 'time-sensitive' && reviewAfter.valueOf() <= now.valueOf()) {
139
throw new Error(`${definition.slug}: review window expired`);
140
}
141
}
docs/scripts/verify-kb.ts
+3
-5
@@ -68,11 +68,9 @@ function parseOptions(argumentsList: string[]): CliOptions {
68
}
69
70
/**
71
- * `buildKbCatalog` throws when any published guide's review window has expired,
72
- * because the docs build must not ship unreviewed content. This tool has to keep
73
- * working in exactly that state — an expired window is a finding to report, not a
74
- * reason to go blind — so catalog assembly runs with a floor date and expiry is
75
- * re-checked against the real clock inside `verifyKb`.
71
+ * `buildKbCatalog` rejects expired time-sensitive guides. The verifier must still
72
+ * report them, so catalog assembly runs with a floor date and `verifyKb` checks
73
+ * every published guide's review deadline against the real clock.
74
*/
75
function loadCatalogIgnoringExpiry() {
76
const manifest = JSON.parse(readFileSync(join(KB_ROOT, 'manifest.json'), 'utf8')) as KbManifest;
docs/tests/static/kb-catalog.test.ts
+18
-2
@@ -404,9 +404,25 @@ This is the second safe answer.`);
404
expect(heldGuides).toHaveLength(0);
405
});
406
407
- test('rejects an expired published review window', () => {
407
+ test('keeps an evergreen guide published after its review deadline without extending it', () => {
408
+ const catalog = buildKbCatalog(
409
+ manifest({ reviewAfter: '2026-07-22' }),
410
+ () => source,
411
+ new Date('2026-07-23')
412
+ );
413
+
414
+ expect(getPublishedKbGuides(catalog).map(guide => guide.slug)).toEqual(['stable-answer']);
415
+ expect(catalog.guides[0]?.reviewAfter).toBe('2026-07-22');
416
+ expect(catalog.guides[0]?.lastVerifiedAt).toBe('2026-07-21');
417
+ });
418
+
419
+ test('rejects an expired published time-sensitive review window', () => {
420
expect(() =>
409
- buildKbCatalog(manifest({ reviewAfter: '2026-07-20' }), () => source, new Date('2026-07-21'))
421
+ buildKbCatalog(
422
+ manifest({ freshness: 'time-sensitive', reviewAfter: '2026-07-20' }),
423
+ () => source,
424
+ new Date('2026-07-21')
425
+ )
426
).toThrow('review window expired');
427
});
428