You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
- [ ] 4. Map each release-note item to PF MCP impact
25
-
- [ ] 5. Run tests (types, unit, e2e, audit)
26
-
- [ ] 6. Write report under `reports/` with required filename
27
-
- [ ] 7. Present report and ASK for permission to apply fixes
28
-
```
29
-
30
-
### Step 1: Versions and release notes
31
-
32
-
1. Read `package.json` and `package-lock.json` (`node_modules/zod/package.json` if installed).
33
-
2. Note **previous** version from `git log -1 -- package.json` or the bump PR/commit.
34
-
3. Fetch release notes for the target minor/major (method-agnostic - release page, GitHub API, packaged changelog, or any fetch tool available in the agent environment):
- For patch bumps within the same minor (e.g. 4.4.1 → 4.4.3), use the **minor** release notes (e.g. v4.4.0) plus any patch-specific notes if present.
37
-
-**Offline fallback:** If release notes cannot be retrieved, state that limitation and continue from `package.json`, lockfile, and the implementation audit below only.
38
-
4. List **potentially breaking**, **other fixes**, **performance**, and **locales** sections from the release.
39
-
5.**Implementation audit (conditional)**: If release notes are ambiguous or the bump is minor/major:
40
-
- Prefer `node_modules/zod/src/` when shipped (see `files` in `node_modules/zod/package.json`).
41
-
-**Fallback:** If `src/` is absent, read `main`, `module`, and `exports` in `node_modules/zod/package.json`, then search those published paths (e.g. `index.js`, `v3/`) for internal brands and interop behavior.
42
-
- Verify: persistence of `_def` / `_zod`; stability of loose/passthrough logic; v3 interop within the v4 package.
43
-
44
-
### Step 2: Repo guidelines
45
-
46
-
Read (do not duplicate into the report):
47
-
48
-
-`CONTRIBUTING.md` — testing, TypeScript, AI agent section
-`docs/development.md` — Zod vs JSON Schema for tools/plugins
52
-
53
-
### Step 3: Codebase inventory
54
-
55
-
Run all commands in [reference.md — Grep patterns](reference.md#grep-patterns). Read hot paths in [reference.md — Key files](reference.md#key-files).
56
-
57
-
Record: **used** vs **not used** per release-note item.
58
-
59
-
#### Step 3b: Compatibility checks
60
-
61
-
Per [reference.md — Compatibility Policy](reference.md#compatibility-policy-zod-detection):
62
-
63
-
- New detection logic must be **additive** (e.g. public `.def` alongside `_zod` / `_def`).
64
-
- Do **not** remove legacy `_def` or v3-compatible paths unless Zod release notes show a concrete conflict (false positives or crashes).
65
-
66
-
### Step 4: Impact matrix
67
-
68
-
For **every** release-note bullet (breaking, fixes, performance, locales), fill one row in the report tables:
69
-
70
-
| Column | Content |
71
-
|--------|---------|
72
-
|**Release note**| Short label from Zod release |
73
-
|**Used in PF MCP?**| Yes / No / Indirect — cite file or grep |
74
-
|**Impact**| None / Low / Medium / High — effect on tools, plugins, manifests, tests |
75
-
|**Priority**| See priority rules below |
76
-
|**Recommended fix**| Concrete action, or `None`|
77
-
78
-
-[ ]**Check Recurring P2s**: Always include the "Updated P2 Recommendations (Recurring)" from `reference.md` in the "Recommended fixes" (consolidated) section of the report, even if the primary tests pass.
79
-
80
-
**Priority rules (PF MCP):**
81
-
82
-
| Priority | When |
83
-
|----------|------|
84
-
|**P0**| Tests fail, types fail, or runtime/tool registration breaks after bump |
85
-
|**P1**| Used API with behavior change; snapshots or plugin manifests need update |
86
-
|**P2**| Optional hygiene (adding modern `.def` detection, docs for plugin authors). **Note**: Do NOT remove legacy `_def` or v3-compatible detection logic unless it contradicts the new Zod version. |
87
-
|**None**| Not used, or positive/neutral change with passing tests |
88
-
89
-
For filled-row patterns (breaking / fixes / summary), see [reference.md — Example impact rows](reference.md#example-impact-rows-pf-mcp).
90
-
91
-
### Step 5: Tests
92
-
93
-
From repo root:
94
-
95
-
```bash
96
-
npm run test:types
97
-
npx jest --selectProjects unit
98
-
npm run test:integration
99
-
npm run test:audit
100
-
```
101
-
102
-
Record pass/fail counts. Note: full `npm test` may fail on `auditor/` ESLint — treat as pre-existing unless the Zod bump touched `auditor/`.
103
-
104
-
**Important Behavioral Rule**:
105
-
- If tests fail due to Zod (**P0**): Note the failures in the report. Apply minimal P0 fixes only if strictly necessary to verify the bump's safety, and document them clearly.
106
-
- For **P1** and **P2** items: **Do NOT apply any code changes** (even optional ones like `z.url()` migration) during this step. These must be recommended in the report first.
107
-
108
-
If tests fail due to Zod (P0): fix code, update snapshots only when output change is correct (`jest -u` scoped to affected files).
109
-
110
-
### Step 6: Write the report
111
-
112
-
**Directory:**`reports/` at repository root (gitignored; not for commit unless the user asks). Ensure an allowance for an existing directory is made (e.g., `mkdir -p`) to avoid blowing away or failing on the previous report directory.
5.**Release notes vs. PatternFly MCP** — separate tables for breaking / other / performance / locales
125
-
6. Documentation and agent guidance status
126
-
7.**Recommended fixes** — consolidated list sorted by priority (P0 → P2)
127
-
8. Conclusion and references (release URL, bump commit if any)
128
-
129
-
Do not commit the report unless the user asks.
130
-
131
-
### Step 7: User summary and Permission
132
-
133
-
Reply with:
134
-
135
-
- Report path
136
-
-**Executive summary verdict table** from the report (code changes required, documentation updates required, risk level — do not collapse to a single safe/needs-work line)
137
-
- Count of P0/P1/P2 items
138
-
- Link to release notes
139
-
-**🛑 Permission Request**: Ask the user: *"Would you like me to proceed with the recommended P1/P2 fixes listed in the report?"*
140
-
141
-
**DO NOT** modify the codebase further until the user explicitly grants permission.
142
-
143
-
## Quick PF MCP facts
144
-
145
-
-**Zod is Required for SDK Routing**: Any tool registered with the MCP SDK MUST have a Zod instance for its `inputSchema` (even a minimal one like `z.any()`) to ensure the SDK passes user arguments correctly to the handler. Without it, handlers receive only a context object.
146
-
- Internal tools **require** Zod or raw Zod shapes; JSON Schema is converted via `src/server.schema.ts`.
147
-
- Core APIs: `fromJSONSchema`, `toJSONSchema`, `z.looseObject`, raw shapes with `.optional()` — not `z.undefined()`, `z.tuple()`, `.merge()`.
- Read `package.json`, `package-lock.json`, and `node_modules/zod/package.json` if installed.
19
+
- Note **previous** version from `git log -1 -- package.json` or the bump PR/commit.
20
+
- Fetch release notes for the target minor/major (release page, GitHub API, packaged changelog, or any fetch tool): `https://github.com/colinhacks/zod/releases/tag/v{VERSION}`.
21
+
- For patch bumps within the same minor (e.g. 4.4.1 → 4.4.3), use the **minor** release notes (e.g. v4.4.0) plus patch-specific notes when present.
22
+
-**Offline fallback:** If release notes cannot be retrieved, state that limitation and continue from `package.json`, lockfile, and the inventory/audit steps only.
23
+
- Extract **potentially breaking**, **other fixes**, **performance**, and **locales** sections.
24
+
- If notes are ambiguous or the bump is minor/major, follow [reference.md — Audit depth policy](reference.md#audit-depth-policy) (prefer `node_modules/zod/src/` when shipped; otherwise published entry points from `package.json``exports`).
25
+
26
+
2.**Repo guidelines**
27
+
- Read (do not paste into the report): `CONTRIBUTING.md`, `guidelines/agent_coding.md`, `guidelines/agent_testing.md`, `docs/development.md`.
28
+
29
+
3.**Codebase inventory**
30
+
- Run all commands in [reference.md — Grep patterns](reference.md#grep-patterns). Read [reference.md — Key files](reference.md#key-files).
31
+
- Record **used** vs **not used** per release-note item.
32
+
- Apply [reference.md — Compatibility policy (Zod detection)](reference.md#compatibility-policy-zod-detection): new detection must be **additive**; do not remove `_def` or v3 paths unless release notes show a concrete conflict.
33
+
34
+
4.**Impact matrix**
35
+
- For **every** release-note bullet (breaking, fixes, performance, locales), add one row to the report tables. Columns: **Release note**, **Used in PF MCP?** (Yes / No / Indirect — cite file or grep), **Impact** (None / Low / Medium / High), **Priority**, **Recommended fix** (or `None`). Priority rules: [reference.md — Priority rules](reference.md#priority-rules-pf-mcp).
36
+
- Always include [reference.md — Updated P2 recommendations (Recurring)](reference.md#updated-p2-recommendations-recurring) in the report **Recommended fixes** section, even when tests pass.
37
+
- Row patterns: [reference.md — Example impact rows](reference.md#example-impact-rows-pf-mcp).
38
+
39
+
5.**Tests**
40
+
From repo root:
41
+
42
+
```bash
43
+
npm run test:types
44
+
npx jest --selectProjects unit
45
+
npm run test:integration
46
+
npm run test:audit
47
+
```
48
+
49
+
- Record pass/fail counts. Full `npm test` may fail on `auditor/` ESLint—treat as pre-existing unless the bump touched `auditor/`.
50
+
-**P0 (tests/types/runtime break):** Document failures in the report. Apply only minimal fixes needed to verify bump safety, re-run tests, and note any changes. Update snapshots only when output change is correct (`jest -u` scoped to affected files).
51
+
-**P1 / P2:** Do not change code during this review—list fixes in the report only.
52
+
53
+
6.**Write the report**
54
+
-**Directory:**`reports/` at repository root (gitignored). Run `mkdir -p reports` if needed; do not delete prior reports.
55
+
-**Filename:**`YYYYMMDD-zod-{semver}-update-report.md` (`YYYYMMDD` = report date; `{semver}` = target version without `v`, e.g. `reports/20260521-zod-4.4.3-update-report.md`).
56
+
- Use [reference.md — Report template](reference.md#report-template). Do not commit unless the user asks.
57
+
58
+
7.**User summary**
59
+
- Report path; **executive summary verdict table** from the report (code changes required, documentation updates required, risk level—do not collapse to a single line); P0/P1/P2 counts; link to release notes.
60
+
- Ask: *"Would you like me to proceed with the recommended P1/P2 fixes listed in the report?"*
61
+
- Do not modify the codebase further until the user explicitly grants permission (except minimal P0 fixes from step 5).
-**Zod is required for SDK routing:** Any tool registered with the MCP SDK must have a Zod `inputSchema` (even `z.any()`) so the SDK passes user arguments to the handler. Without it, handlers receive only a context object.
6
+
- Internal tools **require** Zod or raw Zod shapes; JSON Schema is converted via `src/server.schema.ts`.
7
+
- Core APIs: `fromJSONSchema`, `toJSONSchema`, `z.looseObject`, raw shapes with `.optional()` — not `z.undefined()`, `z.tuple()`, `.merge()`.
8
+
- MCP SDK peer: `zod ^3.25 || ^4.0`.
9
+
10
+
## Priority rules (PF MCP)
11
+
12
+
| Priority | When |
13
+
|----------|------|
14
+
|**P0**| Tests fail, types fail, or runtime/tool registration breaks after bump |
15
+
|**P1**| Used API with behavior change; snapshots or plugin manifests need update |
16
+
|**P2**| Optional hygiene (e.g. modern `.def` detection, docs for plugin authors). Do **not** remove legacy `_def` or v3-compatible detection unless the new Zod version contradicts it |
17
+
|**None**| Not used, or positive/neutral change with passing tests |
0 commit comments