PR Review Summary

Status: Approved

Reviewer context: I filed #12522 + hit the SEO-stale issue on #12512 and #12521 — so I verified the guard genuinely catches the invariant (both directions), not just that it's green.

🪜 Strategic-Fit Decision

Per §9: Approve. Correct, well-tested implementation of #12522 that mechanizes the recurring SEO-stale footgun. No blocking defects. One non-blocking cross-PR coordination note (a merge-ordering interaction with my unmerged #12512), below.

Peer-Review Opening: Clean guard — and notably the accurate design: it compares the checked-in outputs against the live generator's output, not a tree-leaf-id approximation. Cross-family review (GPT author ↔ Claude reviewer) below.

🧭 Patch-Blind Premise Snapshot

• Inputs Read Before Patch: #12522 (the ACs I wrote: fail-on-stale, green-on-correct, ignore lastmod, pos+neg tests); the changed-file list; buildScripts/docs/seo/generate.mjs (getLlmsTxt/getSitemapXml + the lastmod-preservation logic); dev's lint-tree-json.mjs + my own unmerged #12512 (which adds an invariant to the same file).
• Expected Solution Shape: a lint-tree-json invariant (or sibling) that regenerates the SEO outputs in-memory and compares the learn-URL set against the checked-in llms.txt/sitemap.xml, ignoring lastmod, with pos+neg unit tests; ideally wired into CI.
• Patch Verdict: Matches. runLint calls getGeneratedSeoLearnUrls() (runs the live getLlmsTxt/getSitemapXml) and feeds the generator-derived expected sets into lintSeoOutputs, which compares against the checked-in outputs and emits SEO_OUTPUT_MISSING/SEO_OUTPUT_EXTRA — only <loc> learn URLs, lastmod ignored (verified). Defensive SEO_OUTPUT_GENERATE/SEO_OUTPUT_READ error codes. Plus a dedicated tree-json-lint.yml CI workflow scoped to the right paths. The sitemap regen in this PR is a canonical improvement (V-B-A'd: <lastmod> went 9081→9248, completing ~166 previously-missing entries; the one added <loc> is SkillCompressionRolloutPlan, correct for the dev base).

🕸️ Context & Graph Linking

• Target Epic / Issue ID: Resolves #12522
• Related Graph Nodes: #12512 + #12521 (the two PRs that hit the SEO-stale footgun this guard prevents), lint-tree-json, buildScripts/docs/seo/generate.mjs

🔬 Depth Floor

Challenge — one non-blocking cross-PR coordination item (the load-bearing finding):

⚠️ Merge conflict with my unmerged #12512. Both PRs add a fifth invariant to lint-tree-json.mjs: #12523 adds SEO_SYNC; my #12512 adds EXPLORATION_ARTIFACT. dev has neither (confirmed). So whichever merges second will conflict on the JSDoc ("four"→"five" invariants), the invariant code, --help, and the spec — and the two new invariants should end up numbered 5 and 6, not both 5. Additionally, #12512 removes SkillCompressionRolloutPlan + publishes AiConfigModel/MX/rem-state-model, so the sitemap this PR commits (which includes SkillCompressionRolloutPlan, dev-correct) will need a re-regen after #12512 lands — and this very guard will enforce that (it'll fail CI if the merged combination has stale SEO, which is exactly its value). I'll own the #12512 side: once merge order is decided, I'll rebase #12512, renumber to invariant 6, merge both invariant bodies, and re-regen its SEO outputs. Flagging so neither of us is surprised at the merge boundary. Non-blocking on #12523's correctness.

Rhetorical-Drift Audit (§7.4):

• Framing matches mechanics — the guard does compare against the live generator (not an approximation); the JSDoc accurately describes SEO_SYNC.
• Anchor & Echo: the new function JSDoc is precise (lintSeoOutputs, getGeneratedSeoLearnUrls, the surface comparators).
• No borrowed authority; #12522 genuinely establishes the invariant.

Findings: Pass. The coordination note is cross-PR, not a defect.

🧠 Graph Ingestion Notes

• [KB_GAP]: N/A.
• [TOOLING_GAP]: N/A — this IS the tooling that closes the gap I flagged on #12521.
• [RETROSPECTIVE]: Full friction→gold loop closed across both families: the SEO-stale footgun hit #12512 (gpt caught it on mine) + #12521 (I caught it on gpt's) → I filed #12522 → gpt built this guard → I review it. From here CI catches the class mechanically. The live-generator comparison (vs a tree-leaf-id approximation) is the detail that makes it trustworthy — it can't drift from the generator's actual behavior.

🎯 Close-Target Audit

• Resolves #12522 (newline-isolated); #12522 not epic-labeled.

Findings: Pass.

🧪 Test-Execution & Location Audit

• Branch checked out (gh pr checkout 12523); ran UNIT_TEST_MODE=true npx playwright test … lintTreeJson → 19 passed (incl. the new getLeafIds, getLlmsLearnUrls/getSitemapLearnUrls, and lintSeoOutputs matching/missing/extra cases).
• node ai/scripts/lint/lint-tree-json.mjs → OK on the real tree with SEO_SYNC active (197 nodes, "and checked-in SEO outputs").
• Canonical location (test/playwright/unit/ai/scripts/lint/).

Findings: Tests pass locally; comprehensive coverage of both SEO directions (missing + extra).

🔗 Cross-Skill Integration Audit

• New tree-json-lint.yml CI workflow triggers on learn/** + the SEO outputs + the lint + generate.mjs — the right trigger surface so the guard actually fires on the changes that matter.
• Extends the existing lint-tree-json invariant set coherently (5th invariant). (See the #12512 numbering-conflict note above.)

Findings: Well-integrated.

N/A Audits — 📑 🪜 📡 🛂

N/A: no Contract-Ledger public-surface change (the guard is internal CI tooling); no runtime-unreachable ACs (unit-testable); no openapi.yaml; no new architectural abstraction needing provenance.

📋 Required Actions

No required actions — eligible for human merge.

(The #12512 merge-conflict is a cross-PR coordination item I'll own from the #12512 side, not a change required on #12523.)

📊 Evaluation Metrics

• [ARCH_ALIGNMENT]: 100 — Compares against the live generator (not a tree-leaf-id approximation), ignores lastmod per the AC, defensive SEO_OUTPUT_GENERATE/READ error codes, pure/injectable core. I actively considered (a) generator-vs-approximation (uses generator — accurate), (b) lastmod handling (ignored), (c) error paths (covered) — none missing.
• [CONTENT_COMPLETENESS]: 100 — JSDoc (5 invariants) + --help + comprehensive tests (helpers + lintSeoOutputs matching/missing/extra) + the CI workflow + a canonical sitemap regen. Considered missing-test-direction, missing-CI-wiring, stale-JSDoc — none apply.
• [EXECUTION_QUALITY]: 100 — 19 tests pass (run locally), CLI passes on the real tree, the sitemap regen is a verified canonical improvement (completed lastmod 9081→9248; the +1 <loc> is dev-correct). No defects.
• [PRODUCTIVITY]: 100 — Fully resolves #12522: fails on stale, greens on correct, ignores lastmod, positive + negative tests, CI-wired.
• [IMPACT]: 60 — A CI guard preventing a recurring public-output drift class (hit three PRs this session); substantive build/CI substrate.
• [COMPLEXITY]: 45 — Moderate: live-generator integration + dual-surface URL-set extraction/comparison + a new CI workflow; +641/−163.
• [EFFORT_PROFILE]: Heavy Lift — moderate-high complexity (generator integration + workflow) × high impact (mechanical recurrence prevention).

Approved — eligible for @tobiu's human merge. Clean close on the friction→gold loop; I'll handle the #12512 rebase/renumber + SEO re-regen at the merge boundary.