fix: DevKit 1.2.1 legacy manifest validation hotfix

[Ayleovelle]

Summary

Hotfix for the substantive Sourcery finding posted after #29 merged: #29 (comment)

• Enforce the closed expected field set of .codex-plugin/plugin.json, rejecting missing fields and extra entries such as hooks, agents, skills, commands, or unknown metadata.
• Add source and CLI rejection tests for extra/missing keys; verify the shipped checker rejects added hooks in both independently extracted lean and marketplace artifacts.
• Bump both plugin manifests, Python project and locked root-package metadata to 1.2.1; update current-version documentation and changelog.

This remains a read-only diagnostic. It does not prove arbitrary modified code is safe or grant any host/execution authority. No runtime tool, permission, transport or dependency upgrade is included.

Verification

• Final affected package/metadata/real-stdio suite: 57 passed, 1 skipped, 8 subtests passed (includes both extracted launch formats).
• Changed Python syntax and repository-configured test lint pass; compatibility checker passes the CI E/F checks; formatting and git diff --check pass.
• uv lock --check passes. Only the root project version changed in the lock; dependencies are unchanged.
• Published Git tree exactly equals the locally tested tree f27abf30e91b67277865ae5afb2aafe765732b50.
• New GitHub CI is pending. Full platform suite is not claimed rerun locally; feat: DevKit 1.2.0 — portable plugins and compatibility preflight #29's documented baseline constraints remain applicable.

No release/tag or marketplace publication has been performed.

Summary by Sourcery

Harden legacy manifest validation and release the package as version 1.2.1.

Bug Fixes:

• Harden compatibility validation to reject retained Codex manifests with missing or unexpected fields, including unreviewed hooks, agents, skills, commands, and metadata entries.

Enhancements:

• Keep compatibility checks read-only and fail closed without changing runtime or host authorization boundaries.

Build:

• Bump plugin, Python project, and lockfile metadata to version 1.2.1.

Documentation:

• Update English and Chinese user documentation, compatibility guidance, artifact examples, and changelog for the 1.2.1 hotfix.

Tests:

• Add regression coverage for extra and missing manifest fields across source checks, CLI validation, and independently extracted artifacts.

[sourcery-ai]

Reviewer's Guide

This hotfix makes retained legacy manifest validation fail closed on any missing or unexpected field, adds coverage through source, CLI, and independently extracted artifact paths, and updates package metadata and documentation for version 1.2.1 without changing dependencies, runtime behavior, or execution authority.

Flow diagram for closed legacy manifest validation

flowchart LR
    Inputs["Source package, CLI input, or extracted artifact"] --> Checker["check_compatibility.load"]
    Checker --> Fields["Compare legacy manifest fields"]
    Fields -->|"Exact set: IDENTITY, mcpServers, interface"| Accept["Compatibility check passes"]
    Fields -->|"Missing or extra field"| Reject["Raise PackageError: legacy_manifest_fields_differ"]

Loading

File-Level Changes

Change	Details	Files
Harden legacy manifest validation with a closed, exact field set.	Require exactly the reviewed identity, mcpServers, and interface fields. Reject missing fields and unreviewed extras such as hooks, agents, skills, commands, and unknown metadata. Return the existing fail-closed diagnostic without adding execution authority.	.codex-plugin/check_compatibility.py
Add regression coverage across source checks, CLI checks, and extracted release artifacts.	Test extra and missing legacy fields through the Python checker and CLI. Verify both independently extracted artifact formats reject injected hooks. Assert failures remain non-authorizing and do not execute or consume injected entries.	mcp-tools/tests/test_package_compatibility.py
Release the manifest-validation hotfix as version 1.2.1.	Bump both plugin manifests, the Python project, and the locked root package metadata. Update metadata assertions for the new version while preserving dependencies.	.codex-plugin/plugin.json plugin.json mcp-tools/pyproject.toml mcp-tools/uv.lock mcp-tools/tests/test_bugkiller_metadata.py mcp-tools/tests/test_primary_artifact.py
Document the 1.2.1 compatibility hardening and updated artifact names.	Update English and Chinese version references, hotfix notes, and build examples. Add changelog and compatibility guidance clarifying the closed manifest policy and diagnostic boundaries.	CHANGELOG.md README.md README.zh-CN.md docs/compatibility/codex-2026-09.md

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey - I've found 1 issue

Prompt for AI Agents

Please address the comments from this code review:

## Individual Comments

### Comment 1
<location path="docs/compatibility/codex-2026-09.md" line_range="108-110" />
<code_context>
 These links explain the migration decisions. They are not runtime authority or
 permission receipts, and future availability must be checked again.
+
+## 1.2.1 retained-manifest hardening
+
+Both manifests have closed field sets in the compatibility preflight. Extra retained Codex keys (including `hooks`, `agents`, and `skills`) or missing expected keys make the diagnostic fail. This validates the reviewed package shape, not the safety of arbitrary modified code, a signature, host permission, or execution authority.
</code_context>
<issue_to_address>
**nitpick:** The compatibility document's new 1.2.1 section conflicts with its unchanged introduction, which still presents DevKit 1.2.0 as the current release; readers receive contradictory current-version guidance.

**Suggested fix:** Update the document's current-release references from 1.2.0 to 1.2.1 while retaining historical references where appropriate.
</issue_to_address>

Sourcery assessment

Needs a human reviewer. If the closed-field check is wrong, it could reject a valid legacy manifest and prevent the compatibility preflight or package workflow from accepting it, or fail to enforce the reviewed runtime surface. Reverting the checker and versioned package changes restores the prior behavior, with no persisted data or irreversible side effect.

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

[sourcery-ai]

nitpick: The compatibility document's new 1.2.1 section conflicts with its unchanged introduction, which still presents DevKit 1.2.0 as the current release; readers receive contradictory current-version guidance.

Suggested fix: Update the document's current-release references from 1.2.0 to 1.2.1 while retaining historical references where appropriate.