Skip to content

docs(plugin-ops): document the verify-plugin --json output as a contract - #120

Merged
kyle-sexton merged 2 commits into
mainfrom
docs/verify-plugin-json-shape
Oct 11, 2026
Merged

kyle-sexton merged 2 commits into
mainfrom
docs/verify-plugin-json-shape

Conversation

@kyle-sexton

@kyle-sexton kyle-sexton commented Oct 11, 2026 •

Copy link
Copy Markdown
Member

Refs: #117

Summary

Documents the --json output of validate-marketplace.mjs as a contract in the verify-plugin skill, links the shape test to it, and cites Codex's source for the skipped-catalog-slot test. User goal: a consumer of --json can rely on the key list and knows which changes are breaking. Vertical slice: plugin-ops / verify-plugin. Bumps plugin-ops to 0.2.4.

Fix

  • SKILL.md: new "JSON output" section with a table of target, kind, catalog, manifests, errors, warnings (order, type, meaning); adding a key is compatible, renaming or removing one is breaking.
  • validate-marketplace.test.mjs: comment pointing the key-list assertion at that section; comment citing is_file() over MARKETPLACE_MANIFEST_RELATIVE_PATHS in codex-rs/core-plugins/src/marketplace.rs at rust-v0.162.0 (symbols verified at the tag via the GitHub API on 2026-10-10).
  • Version bump in plugin.json and tests/plugin-ops-plugin.test.mjs.

Verification

  • npm test: 176 pass, 0 fail.
  • npm run validate: no failures.
  • $skill-creator quick validator: python ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py plugins/plugin-ops/skills/verify-plugin (run with PyYAML through uv run --with pyyaml): Skill is valid!
  • Native surfaces and context inputs unchanged; no ports, adapters or defaults introduced.

Upstream consulted:

Related

Refs: #117

🤖 Generated with Claude Code

kyle-sexton and others added 2 commits October 10, 2026 23:52
Add a JSON output section to verify-plugin listing the top-level keys in order,
their types, and the compatibility rule. Point the shape test at that section
and cite Codex's is_file() catalog-slot check in the skip test. Bump plugin-ops
to 0.2.4.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kyle-sexton
kyle-sexton marked this pull request as ready for review October 11, 2026 03:53
@claude

claude Bot commented Oct 11, 2026 •

Copy link
Copy Markdown

Claude finished @kyle-sexton's task in 29s —— View job


Security review

  • Gather context (PR diff, changed files)
  • Apply skip gate
  • Review changed files for security-relevant surface
  • Post findings

Result: no security issues found.

This PR is documentation-only plus a version bump:

  • plugins/plugin-ops/skills/verify-plugin/SKILL.md — adds a "JSON output" section documenting the existing --json key list as a stability contract. No behavior change.
  • plugins/plugin-ops/skills/verify-plugin/scripts/validate-marketplace.test.mjs — adds two comments (pointing to the SKILL.md contract and citing Codex's is_file() check in codex-rs/core-plugins/src/marketplace.rs). No assertion logic changed.
  • plugins/plugin-ops/.codex-plugin/plugin.json and tests/plugin-ops-plugin.test.mjs — version bump 0.2.3 → 0.2.4, kept in sync.

Skip-gate check: no code paths, parsing, file I/O, or trust boundaries are touched — only prose and comments. No standing instruction (AGENTS.md/CLAUDE.md/rules/skill body) is deleted, narrowed, or softened here; the change only adds documentation, so the instruction-surface-deletion lens doesn't apply. No injection surfaces, credential handling, or authorization logic in scope.

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 11, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-11T03:56:53.400260Z 694434c Draft marked ready
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@claude

claude Bot commented Oct 11, 2026 •

Copy link
Copy Markdown

Claude finished @kyle-sexton's task in 2m 14s —— View job


Review of PR #120 — docs(plugin-ops): document the verify-plugin --json output as a contract

  • Gather context (diff, changed files, CLAUDE.md/REVIEW.md)
  • Understand request (run /review:code-review)
  • Review changed files for correctness/maintainability
  • Post findings

Scope: pure documentation + version bump (no runtime logic changed). Diffed against origin/main and read all 4 changed files plus validate-marketplace.mjs itself to check the new contract claims against actual code.

Findings: none.

Verified by reading the implementation, not just the PR's own claims:

  • The new "JSON output" table in SKILL.md (key names, order: target, kind, catalog, manifests, errors, warnings, types, and kind: null semantics) matches the literal object built in validateTarget() (plugins/plugin-ops/skills/verify-plugin/scripts/validate-marketplace.mjs:507) and the format enum (agent-plugin/codex/claude/cursor) matches CATALOGS/LEGACY_MANIFESTS (lines 38-46, 273).
  • "Paths are absolute" holds for target, catalog, and manifests[].plugin/.manifest/.overlay — all are built from path.resolve/path.join against an already-resolved absolute root (resolveContained, line 169; validateTarget, line 506).
  • The test comments added (validate-marketplace.test.mjs) correctly point at the new SKILL.md anchor and at the real is_file() check in resolveCatalog (line 492).
  • Version bump is consistent across plugin.json and tests/plugin-ops-plugin.test.mjs; no stray 0.2.3 references remain elsewhere in the repo.

Not independently verified: the PR's npm test (176 pass) / npm run validate results, and the upstream rust-v0.162.0 citation in the test comment — I didn't have tool access to run the test suite or fetch the upstream file in this session, so those are author-claimed and unverified rather than confirmed by me.

No inline comments were needed — no finding met the bar for one.

Branch: docs/verify-plugin-json-shape

@github-actions

github-actions Bot commented Oct 11, 2026 •

Copy link
Copy Markdown

claude-security-review has reviewed this pull request through 694434c; a later push is reviewed from there.

@claude

claude Bot commented Oct 11, 2026 •

Copy link
Copy Markdown

Claude finished @kyle-sexton's task in 47s —— View job


Security review — no issues found

Scope: incremental — reviewed only the change since the last-reviewed commit (15da8bd), confined to plugins/plugin-ops/skills/verify-plugin/SKILL.md per .claude-lane/incremental.diff. All other files in this PR were reviewed at 15da8bd and are unchanged since.

  • Read .claude-lane/incremental.diff for the exact change under review
  • Assess security relevance of the diff
  • Check instruction-surface lens (guardrail removal/narrowing)
  • Post final findings

What changed

One line in the "JSON output" contract table in SKILL.md, clarifying when kind is null:

-| `kind` | `"marketplace"`, `"plugin"`, or `null` | What the target was; `null` when neither was found. |
+| `kind` | `"marketplace"`, `"plugin"`, or `null` | What the target was; `null` when the target is neither or could not be inspected. |

Link

Assessment

This is a prose-only clarification to a documentation table describing the --json output contract of validate-marketplace.mjs. It:

  • Introduces no code change, no new input handling, and no new trust boundary.
  • Does not touch command execution, path handling, credentials, or tokens.
  • Is not an instruction-surface deletion/narrowing — it widens the documented set of cases that already produce kind: null, matching existing/updated behavior more precisely; it removes no guardrail and leaves the breaking-change rule ("renaming or removing a key, or changing its type, is breaking") intact just below it.

No security-relevant surface in this increment. No findings to report.

@github-actions

Copy link
Copy Markdown

claude-review has reviewed this pull request through 694434c; a later push is reviewed from there.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 694434c9be

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@kyle-sexton
kyle-sexton merged commit 2d92547 into main Oct 11, 2026
9 checks passed
@kyle-sexton
kyle-sexton deleted the docs/verify-plugin-json-shape branch October 11, 2026 03:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant