Mergecraft

Mergecraft is an Agent Plugins GitHub authoring and pull-request lifecycle package with a native Claude adapter. It owns exact human-facing Issue and pull-request body authoring, Issue–PR contribution ledgers and Development links, reviewer navigation, guarded PR publication, Graphite draft transport, feedback coordination and interaction, review readiness, merge closeout, and stacked fixups. topology.json is the only machine-readable graph and operation-ownership authority. Its schema_version versions Mergecraft's local topology shape, not a repository-wide interchange schema.

Canonical PR publication requires every caller to select required or explicit not-required review and its specialist inventory before invoking the writer or freezing the candidate. The writer's ordinary independent review gate accepts a verified bare clean Tricritical hand-back for the current title/body, inputs, requirements, scopes, and evidence dependencies. not-required records no witnessed provenance and does not waive that review. Callers preserve the selection through publication, readiness, and resume. required adds the authenticated Task Witness gate and remains unavailable without its separately qualified integration. Task Witness is optional future equipment for callers that need its stronger cross-harness evidence contract.

Public skills

There are no compatibility routers and no public PR-creation orchestrator. Semantic sibling links remain relative within this plugin. Cross-plugin calls use qualified identities.

Issue–PR relations

Relation maintenance applies to new contributions, material contribution or completion-scope changes, explicit repairs, and applicable merge consequences. Unchanged intent and unrelated edits skip acquisition. Both bodies retain all verified contributions using stable links and useful role annotations, without copied titles or status. Native Development links follow the Issue repository's closure policy and available capacity; they are not a one-to-one relation.

Partial contributions need a usable observation that auto-close is disabled. Otherwise, native links require evidence that the triggering merge satisfies the Issue's completion gates. The setting cache reuses an observation throughout the task, including resumes, and defaults to 30 days across tasks, with optional no expiry. Cache hits retain the original timestamp. Explicit refresh, a newly observed change, or contradictory behavior invalidates affected plans. No setting changes occur during installation or ordinary relation handling.

The relation contract defines evidence, state-read budgets, disclosure, capacity, and recovery. The public helper returns finite plans and verifies individually authorized effects. It never closes or reopens Issues. Existing PR ledger edits use the bounded publication mode, which preserves title, state, and unrelated bytes even when branches no longer exist. Its receipts establish only those edits; canonical publication and readiness retain their own gates.

Markdown authoring projections

The canonical portable contract is skills/writing-github-issue-and-pr-markdown/references/authoring-contract.md. The standalone public skill authors any of the seven covered bodies. Each current semantic writer also carries a generated byte-identical references/github-markdown-authoring.md: writing-reviewable-pr-descriptions for pull-request bodies, interacting-with-pr-review-feedback for review-thread replies and PR conversation responses, and getting-prs-merged for its selected CodeRabbit pull-request conversation-comment bytes. Other lifecycle skills delegate body content or actuation and do not become duplicate semantic writers.

Change only the canonical source. From the repository root, run python scripts/validate_mergecraft.py . --write-markdown-projections to regenerate the three writer-local projections. This command preserves the content lock and permits stale behavior evidence during canonical development. Inspect the projection diff and refresh the evidence for the changed candidate, then run python scripts/validate_mergecraft.py . --write-content-lock. The lock command validates the current projections and evidence before writing only the ordinary Mergecraft content lock. The two writing modes are mutually exclusive; each uses the generated-artifact recovery transaction for its own files.

Run python scripts/validate_mergecraft.py . after both steps. A completed projection refresh leaves the previous content lock stale until the lock step succeeds. Source-stage validation checks discovery, projection links, byte equality, and evidence bindings but skips the ordinary content lock. A projection that drifts or a supported route that cannot discover the direct skill is not evidence that the capability is available.

Operation registry

The internal merge actuator, top-level comment actuator, and CI adapter are operation-specific and are not public skills. The merge actuator performs one fully bound write and returns a reread receipt to the merge-outcome coordinator. The CI seam preserves github:gh-fix-ci as its upstream, independently updateable implementation while limiting delegation to Actions diagnosis and separately authorized scoped fixes.

Feedback responses use two Provingkit-owned operation-specific actuators: one replies in an existing review thread, and one creates a PR conversation comment for an exact conversation or submitted-review source. The semantic response owner applies selected writing policy before the portable writer fixes the body, then forwards its exact bytes unchanged. Both actuators retain typed source correlation, caller-key replay protection, authoritative provider receipts, and append-only semantic outcomes. An unknown write requires same-intent reconciliation and cannot be bypassed with a new key.

One fold-owned private response-identity module supplies the runtime's closed reconciliation decisions. It compares exact provider-observable correlation, keeps same-result effective unknowns unassigned, and owns the full typed identity lifecycle as one record transaction. Head-bound evidence stays in all admission and prewrite checks; it is excluded only from result attribution.

The interaction runtime and fold also share skills/interacting-with-pr-review-feedback/scripts/response_source_owner.py. It constructs permanent source ownership from stable typed Repository, pull request, source, and exact revision identities while mutable repository and PR context remains in the full validation binding.

The response path preserves thread state and performs no reactions, thread resolution, review submission, or Issue lifecycle operations. It has no Agentworks runtime or schema dependency. Several responses remain independent one-intent calls with no batch atomicity or rollback. The response contract defines the supported evidence and reconciliation boundaries.

The review-voice reference and its Tidesmith declaration remain owned by the review-voice projection work. Until a selected policy route is available, the caller records that limitation and applies its ambient writing instructions before freezing the response body. Response-runtime qualification does not establish that missing policy route, cross-machine serialization, release eligibility, or production authority.

Each public component in topology.json declares its trigger, modes, authority, inputs, outputs, forbidden reverse calls, loop owner, and terminal statuses. Together with the call graph and sole operation owners, these contracts are the caller/callee boundary. Lifecycle coordination stays with the current public owners; there is no additional public review-orchestration layer.

Layout

plugins/mergecraft/
├── plugin.json
├── .claude-plugin/plugin.json
├── skills/
├── topology.json
├── CHANGELOG.md
└── LICENSE

Package validation

From the package root:

python3 skills/writing-reviewable-pr-descriptions/scripts/validate_change_navigation.py --help
python3 skills/writing-reviewable-pr-descriptions/scripts/validate_relation_ledger.py --help
python3 skills/publishing-reviewable-prs/scripts/create_reviewable_pr.py --help
python3 skills/publishing-reviewable-prs/scripts/update_reviewable_pr.py --help
python3 skills/publishing-reviewable-prs/scripts/audit_reviewable_pr.py --help
python3 skills/publishing-reviewable-prs/scripts/publish_relation_ledger.py --help
python3 skills/maintaining-issue-pr-relations/scripts/relation_state.py --help
python3 skills/graphite/scripts/submit_draft_stack.py --help
python3 skills/getting-prs-merged/scripts/post_coderabbit_comment.py --help
python3 skills/addressing-pr-review-feedback/scripts/review_feedback_state.py --help
python3 skills/interacting-with-pr-review-feedback/scripts/response_cli.py --help

Repository release validation additionally runs scripts/validate_mergecraft.py and the repository-owned unit suites. Canonical development and release evidence lives at evals/mergecraft/, the Markdown writer's skill-local raw eval corpus, tests/plugins/mergecraft/, the public relation command suites tests/test_mergecraft_issue_pr_relations.py and tests/test_mergecraft_pr_relation_ledger.py, and release/plugin-content-locks/mergecraft.json. Skill-local eval resources are package support artifacts, not runtime authority.

The feedback-response experiment binds the raw scenarios, delivered skill and reference bytes, source and test files, completed isolated responses, canonical grading requests, raw grading responses, and the exact grades used by its thresholds. A refreshed artifact requires the complete pre-execution source digest inventory and rejects any packaging-time source difference. It also retains the exact preceding evidence document and zero or more additional excluded experiment documents inside a normalized history envelope. The versioned predecessor boundary accepts the closed legacy schema 1 shape and the closed current schema 2 shape. A schema 2 refresh carries its already-normalized unselected history forward, while its formerly selected records become excluded observations and never enter the new candidate's thresholds. Each embedded with_skill candidate value must hash to the predecessor's own same-index frozen candidate source entry; without_skill remains empty. Other predecessor source entries are retained declarations when their source bytes are absent. Unsupported or malformed predecessor versions are rejected. Each additional document keeps its exact bytes and SHA-256, derives its exclusion reason and recorded completion from that document, and remains separate from selected records. Each counted historical grading coordinate is unique and links to one recorded execution coordinate; duplicate or orphan grading coordinates make the declared experiment malformed. The packager accepts each document through a repeatable --additional-experiment option, so a failed, interrupted, or superseded experiment can be added without replacing earlier history. The envelope marks earlier selected, rejected, and audit records unqualified for the revised candidate and marks fields that were never recorded as unavailable. It promises consistent retention of the declared local documents, not a complete census of model activity. The checked-in document is historical input until revised-candidate qualification regenerates the selected records.

Run python3 scripts/validate_feedback_response_evidence.py . to apply the maintained evidence method. The validator checks exact schemas and byte digests, three repetitions per case and configuration, distinct locally authored session labels, successful completion with nonempty output, absence of tool events, grading-exchange binding, history exclusions, and the grading thresholds. Hashes identify the recorded bytes. Every current manifest expectation has a fixed safety classification and requires three passing candidate repetitions; evidence-local metadata cannot weaken that gate. Hashes neither authenticate a session nor prevent a trusted local author from rewriting data. The validator does not grade behavior itself. Retained experiment documents cannot supply selected executions or grades. Behavioral runs exercise the supplied instructions. Separate subprocess-provider tests exercise the runtime and both response operations without posting to GitHub.

The selected gpt-daybreak-blue-latest runs at high effort pass all 87 candidate judgments across seven cases and three repetitions; the baseline passes 63 of 87. Each execution and grade uses a separate session. Earlier failed or insufficiently isolated runs remain recorded as unqualified history.

The Markdown writer's experiment retains exact requests and responses, source hashes, and runtime observations; its grading records independent judgments and selected repetitions. The current source passes all 72 expectations across eight cases and three isolated, tools-denied runs per case with Claude Code 2.1.273 and claude-opus-5 at high effort. Unchanged baseline inputs reuse their retained controls. Native loading and 11-trigger observations from the earlier source remain historical evidence, not a current-source discovery claim. Failed and superseded executions remain recorded. These are unsigned development observations for the tested configurations; they grant no release, installation, or actuation authority.

The relation procedure's experiment and independent grades bind the current instructions to 51 behavior responses across 17 cases and 13 native discovery decisions. All 195 selected behavior expectations and 13 discovery decisions pass with Claude Code 2.1.273 and claude-opus-5 at high effort. Behavior runs expose no tools; discovery runs expose only Skill and retain the client's bundled runtime skill descriptions. Failed and superseded runs remain unselected, and supplementary response inaccuracies remain recorded. These checks establish the stated expectations and observed loading behavior, not universal response correctness or provider attestation. Publication validation rejects missing, stale, failed, or inconsistent selected evidence. Separate live qualifications cover the relation command and historical PR ledger publisher; their stated GitHub.com cases do not qualify other hosts or every failure mode.