@devries-cameron20 / composio-1 / commits / 2a81e88af
Fork 0

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