fix(docs): prune removed generated skill pages

[yinkev]

What does this PR do?

Removes the stale Kanban Codex Lane documentation page and fixes the generator behavior that left it published after its source skill was removed.

website/scripts/generate-skill-docs.py previously only wrote pages for currently discovered SKILL.md files. It never reconciled the output directory, so deleting a bundled or optional skill left its last generated page indefinitely claiming the skill was still shipped and installed by default.

The generator now computes the expected output set and removes stale pages before writing. Deletion is deliberately fail-safe and narrow: a file is eligible only when it is under the generated bundled or optional trees and contains this generator's exact auto-generated marker. Hand-written documentation remains untouched.

Related Issue

Fixes #71856

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• 🔒 Security fix
• 📝 Documentation update
• ✅ Tests (adding or improving test coverage)
• ♻️ Refactor (no behavior change)
• 🎯 New skill (bundled or hub)

Changes Made

• remove the orphaned autonomous-ai-agents-kanban-codex-lane.md page;
• centralize the generator marker used to identify owned pages;
• prune generated pages that no longer correspond to a discovered source skill;
• preserve live generated pages and adjacent hand-written Markdown;
• add a regression covering live, stale, and hand-written files in the same generated subtree.

How to Test

python -m pytest -q -o addopts= tests/website/test_generate_skill_docs.py
python -m ruff check website/scripts/generate-skill-docs.py tests/website/test_generate_skill_docs.py
python -m py_compile website/scripts/generate-skill-docs.py tests/website/test_generate_skill_docs.py
git diff --check

Expected focused result: 8 passed.

The full generator also completed successfully against current main; its stale-page reconciliation is covered independently so the test does not rewrite the repository docs tree.

Checklist

Code

• I've read the Contributing Guide
• My commit message follows Conventional Commits
• I searched open and merged issues/PRs for this page and generator behavior
• My PR contains only changes related to this fix
• I've run pytest tests/ -q and all tests pass — the focused generator suite passes; the full required matrix is delegated to GitHub CI
• I've added tests for the generator lifecycle bug
• I've tested on macOS Apple Silicon

Documentation & Housekeeping

• Relevant documentation was updated by removing the page for the removed skill
• cli-config.yaml.example — N/A; no config keys changed
• CONTRIBUTING.md / AGENTS.md — N/A; no contributor workflow change
• Cross-platform impact considered; the implementation uses pathlib operations shared by supported platforms
• Tool descriptions/schemas — N/A; no model-facing tool behavior changed

Verification

Generator tests: 8 passed
Ruff:           passed
py_compile:     passed
Generator run:  completed successfully
Diff hygiene:   passed

[monerostar]

monerostar docs/generator spot-check + unit test

Claim: Removing a skill left a published generated Kanban Codex Lane page; generator should prune stale generated pages.

Current main:

• website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-kanban-codex-lane.md still HTTP 200 on raw main
• Bundled skills tree no longer ships kanban-codex-lane under skills/autonomous-ai-agents/ (local install + recent trees)
• prune_stale_generated_pages not present on main generator (PR adds it)

This PR worktree @ 245b2faa:

• Deletes the stale generated page
• Adds prune_stale_generated_pages() gated on GENERATED_PAGE_MARKER (preserves handwritten pages)
• Wires prune into generate path
• New unit test

Tests (native Windows, hermes venv):

pytest tests/website/test_generate_skill_docs.py -q -o addopts=
→ 8 passed

Verdict: LGTM — fixes the real stale-page class (#71856), not just one-off delete. Prefer this over docs-only manual delete without generator reconcile.

Formal Approve blocked (external) — comment only.

Related: #71856

[yinkev]

Thanks for the current-main and Windows spot-check. The stale published page with no matching bundled skill is the exact failure this targets, and the generated-page marker is the safety boundary that prevents handwritten documentation from being pruned. Your unit-test result confirms the intended behavior; no code change is needed from this review.

[teknium1]

Thanks for addressing the generator-level cause, not only the reported page.

Current main still discovers source skills and writes pages without reconciling obsolete generated outputs (website/scripts/generate-skill-docs.py:735-769), so the new marked-page pruning remains a valid fix. The specific Kanban Codex Lane deletion is already present in 355b37622594d8dd8ead25bca1b845e80b54632c; that makes the deletion portion redundant on current main, but does not supersede the generator safeguard or its regression test.

Automated hermes-sweeper review.

[GottZ]

This was generated by AI during triage.

Summary

One PR addresses #71856. #71869 originally removed the orphaned Kanban Codex Lane page and also fixes the underlying generator reconciliation gap by pruning obsolete marker-owned pages while preserving live generated and hand-written documentation; the reported page itself has since been removed from main by commit 355b376.

Related pull requests

• fix(docs): prune removed generated skill pages #71869 best fix — (+62/-296) — keep open with a salvage path: The page deletion is now redundant because commit 355b376 already removed it on main, but the diff still adds the missing marker-gated pruning in website/scripts/generate-skill-docs.py and a regression test proving that stale generated pages are deleted while live and hand-written pages remain. This agrees with the keep_open review on fix(docs): prune removed generated skill pages #71869; the salvageable part is the generator safeguard and its focused test.

Suggested consolidation

Keep #71869 open with a salvage path: rebase it onto main and retain the generator-level pruning plus regression coverage while dropping the already-applied page deletion. As reflected by the automated close verdict on #71856, commit 355b376 resolves the reported stale page, but #71869 still addresses the distinct recurrence mechanism identified in website/scripts/generate-skill-docs.py:735-769. There are no duplicate PRs to close.

Complex graph

flowchart LR
    classDef open fill:#dbeafe,stroke:#1d4ed8,color:#1e3a8a
    classDef merged fill:#dcfce7,stroke:#15803d,color:#14532d
    classDef closed fill:#e5e7eb,stroke:#6b7280,color:#1f2937
    classDef unverified fill:#f3f4f6,stroke:#9ca3af,color:#374151
    classDef best stroke-width:3px,stroke:#b45309
    classDef target stroke-width:3px,stroke:#4338ca
    I71856(["issue #71856 (closed)"])
    P71869["PR #71869 (open)"]
    P71869 -->|best fix| I71856
    class I71856 closed
    class P71869 open
    class P71869 best
    class P71869 target
    click I71856 "https://github.com/NousResearch/hermes-agent/issues/71856"
    click P71869 "https://github.com/NousResearch/hermes-agent/pull/71869"

Loading

Graph: solid arrow = fixes / best fix, dashed arrow = partial or unverified (see edge label); boxed group = PRs duplicating each other; amber border = best fix; indigo border = target; gray node = closed (state tag in the node label).

Cross-PR triage: Reviewed 1 pull request and 1 issue in this complex. Each diff was read against this issue; Assessment working set: 19 kB of PR diffs, 5 kB of issue/PR text, 2 kB of discussion (3 comments), 3 verify verdicts. verdicts reflect diff content, not PR titles. Part of an automated triage batch.

[yinkev]

Author-status audit — corrected 2026-08-05: GitHub now reports this head as mergeable, current-head CI is green, and there are no unresolved inline review threads. The earlier conflict classification was a stale mergeability result. Restoring the PR to ready for review; no branch rewrite is required.