feat(skills): add lifecycle receipts and curator audit

[leo-guinan]

What does this PR do?

Adds a receipt-based lifecycle path for Hermes skills and a deterministic curator audit helper.

The change gives skill authors and reviewers a machine-readable way to record why a skill changed, what evidence supports the change, and whether the skill lifecycle metadata is valid. This helps prevent skills from becoming untracked procedural folklore: useful until the first time nobody remembers why the instruction exists.

The PR intentionally excludes unrelated fork-stabilization work. It is scoped to skill lifecycle receipts, curator audit tooling, docs, and tests.

Related Issue

No existing issue found.

Fixes #

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

• tools/skill_curator_audit.py
  • Adds deterministic audit logic for skill lifecycle guideline compliance.
• tools/skill_manager_tool.py
  • Validates optional metadata.hermes.lifecycle fields in skill frontmatter:
    • status
    • validation_level
    • evidence_count
    • supersedes
• tests/tools/test_skill_curator_audit.py
  • Adds coverage for curator audit output and guideline checks.
• tests/tools/test_skill_manager_tool.py
  • Adds lifecycle metadata validation coverage.
• website/docs/developer-guide/skill-change-receipt-template.md
  • Adds a reusable receipt template for skill changes.
• skills/software-development/systematic-debugging/SKILL.md
• skills/software-development/writing-plans/SKILL.md
  • Adds lifecycle/receipt guidance to existing skill authoring workflows.
• receipts/skill-curator-audit-receipt.json
• receipts/skill-lifecycle-epic-guideline-check.json
• receipts/skill-lifecycle-metadata-receipt.json
  • Adds machine-readable receipts for the lifecycle/audit work.

How to Test

1. Run the focused skill lifecycle and curator audit tests:

   /Users/leoguinan/hermes-agent/venv/bin/python -m pytest tests/tools/test_skill_curator_audit.py tests/tools/test_skill_manager_tool.py -q --tb=short

2. Expected result:

   95 passed in 0.99s
   

3. Check the branch is scoped to the intended files:

   git diff --name-only upstream/main..HEAD

   Expected changed files:

   receipts/skill-curator-audit-receipt.json
   receipts/skill-lifecycle-epic-guideline-check.json
   receipts/skill-lifecycle-metadata-receipt.json
   skills/software-development/systematic-debugging/SKILL.md
   skills/software-development/writing-plans/SKILL.md
   tests/tools/test_skill_curator_audit.py
   tests/tools/test_skill_manager_tool.py
   tools/skill_curator_audit.py
   tools/skill_manager_tool.py
   website/docs/developer-guide/skill-change-receipt-template.md
   

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (fix(scope):, feat(scope):, etc.)
• I searched for existing PRs to make sure this isn't a duplicate
• My PR contains only changes related to this fix/feature (no unrelated commits)
• I've run pytest tests/ -q and all tests pass
• I've added tests for my changes (required for bug fixes, strongly encouraged for features)
• I've tested on my platform: macOS 26.5, Python via /Users/leoguinan/hermes-agent/venv/bin/python

Documentation & Housekeeping

• I've updated relevant documentation (README, docs/, docstrings) — or N/A
• I've updated cli-config.yaml.example if I added/changed config keys — or N/A
• I've updated CONTRIBUTING.md or AGENTS.md if I changed architecture or workflows — or N/A
• I've considered cross-platform impact (Windows, macOS) per the compatibility guide — or N/A
• I've updated tool descriptions/schemas if I changed tool behavior — or N/A

For New Skills

N/A — this PR updates existing skills/docs and adds lifecycle audit/receipt tooling. It does not add a new bundled skill.

Screenshots / Logs

$ /Users/leoguinan/hermes-agent/venv/bin/python -m pytest tests/tools/test_skill_curator_audit.py tests/tools/test_skill_manager_tool.py -q --tb=short
........................................................................ [ 75%]
.......................                                                  [100%]
95 passed in 0.99s

$ git rev-list --left-right --count upstream/main...HEAD
0	1

$ git diff --stat upstream/main..HEAD
 receipts/skill-curator-audit-receipt.json          | 130 +++++++++
 receipts/skill-lifecycle-epic-guideline-check.json |  98 +++++++
 receipts/skill-lifecycle-metadata-receipt.json     |  58 ++++
 .../systematic-debugging/SKILL.md                  |  15 ++
 skills/software-development/writing-plans/SKILL.md |  15 ++
 tests/tools/test_skill_curator_audit.py            | 123 +++++++++
 tests/tools/test_skill_manager_tool.py             |  84 ++++++
 tools/skill_curator_audit.py                       | 297 +++++++++++++++++++++
 tools/skill_manager_tool.py                        |  48 ++++
 .../skill-change-receipt-template.md               |  67 +++++
 10 files changed, 935 insertions(+)

[teknium1]

Thanks for the focused lifecycle-metadata proposal and deterministic-audit tests.

Problems

• tools/skill_manager_tool.py:258 accepts YAML booleans for evidence_count: Python treats bool as an int, so evidence_count: true passes the proposed integer-only validation. Add an explicit boolean rejection and tests for both boolean values.
• Commit 27d2be5d3a00a6df2bb1b96d466f9962f8cb13ac includes receipts that describe work not in this PR: receipts/skill-curator-audit-receipt.json names xitter and creating-skills.md; receipts/skill-lifecycle-epic-guideline-check.json describes ACP work and a merged PR #9. These receipts need to be removed or made accurate before they can be relied on.

Suggested changes

• Decide whether this remains a documented standalone developer utility or integrates with the supported curator. Current CLI dispatch reaches hermes_cli/curator.py:199 and lifecycle transitions are activity-driven in agent/curator.py:305; this PR does not connect its metadata or audit to either path.

Automated hermes-sweeper review.

[teknium1]

YAML true and false decode as Python bool, and bool is an int subclass, so evidence_count: true passes this check. Reject booleans explicitly and add regression cases for both boolean values.