Skip to main content
Glama
naw103

Foremerge

by naw103
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Rust
Local

Publish a provisional ChangeSet

publish_changeset

Record a committed implementation for an intent as a ChangeSet, capturing its diff and fingerprint so verification and acceptance can validate the exact work.

Instructions

Record a finished unit of implementation for your intent so it can be verified and accepted. Use it once the change is committed in your worktree, after check_conflicts and before run_verification. Foremerge snapshots the worktree (defaulting to your registered one), resolves the candidate commit and its diff base, and stores a fingerprint that verification and acceptance are later checked against. files and symbols are inferred only from uncommitted changes, so list them yourself for committed work. The ChangeSet starts PROVISIONAL and the intent becomes PROVISIONAL. Publishing again while the previous ChangeSet is PROVISIONAL or VALIDATED creates a new one, marks the old one SUPERSEDED, and resets verification. Only the intent's owner may publish, while the intent is CLAIMED, IN_PROGRESS, PROVISIONAL or VALIDATED. Git itself is not modified. Returns the ChangeSet, including its chg_ id, fingerprint, and open_conflicts on the intent at that moment.

Input Schema

NameRequiredDescriptionDefault
filesNoChanged file paths. Left empty, they are inferred from uncommitted changes only, so list them for committed work.
testsNoTests you ran yourself. Recorded as history only; acceptance relies on run_verification, not on this list.
git_refNoCandidate commit. Omit it: it defaults to the worktree's HEAD, and acceptance rejects any other commit with STALE_CHANGESET.
summaryYesWhat the change does, in one or two sentences.
symbolsNoCode symbols added or changed. Left empty, they are inferred from uncommitted changes only, so list them for committed work.
agent_idYesYour agent id (agt_...). Must own the intent.
base_refNoTrue diff base when known (for example the fork point of this agent branch); defaults to the candidate commit's first parent.
worktreeNoPath of the Git worktree holding the change. Defaults to your registered worktree, then the server's working directory. Must belong to your registered repository.
contractsNoNamed interfaces or agreements this change affects, for example payment-provider.
decisionsNoDesign decisions a reviewer or later agent should know about.
intent_idYesThe intent (int_...) this implementation fulfils.
provenanceNoOptional JSON object of your own context, such as a prompt or task reference. Foremerge adds Git provenance under provenance.git.
dependenciesNoIntent ids (int_...) this change builds on, and the dependency list acceptance enforces. accept_changeset refuses with UNSATISFIED_DEPENDENCY unless each is ACCEPTED or COMMITTED and its accepted commit (or, once COMMITTED, its integration commit) is in this change's Git history. Intent ids only: not package or library names.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.6.0
    • changedInput schema / properties / dependencies / description
      Previous value: -"Intent ids (int_...) this change builds on, and the dependency list acceptance enforces. accept_changeset refuses with UNSATISFIED_DEPENDENCY unless each is ACCEPTED or COMMITTED and its accepted commit is in this change's Git history. Intent ids only: not package or library names."New value: +"Intent ids (int_...) this change builds on, and the dependency list acceptance enforces. accept_changeset refuses with UNSATISFIED_DEPENDENCY unless each is ACCEPTED or COMMITTED and its accepted commit (or, once COMMITTED, its integration commit) is in this change's Git history. Intent ids only: not package or library names."
  2. Changed18 schema fields changedv0.4.3
    • addedInput schema / properties / agent_id / description
      Added value: +"Your agent id (agt_...). Must own the intent."
    • addedInput schema / properties / contracts / description
      Added value: +"Named interfaces or agreements this change affects, for example payment-provider."
    • addedInput schema / properties / decisions / description
      Added value: +"Design decisions a reviewer or later agent should know about."
    • addedInput schema / properties / decisions / items / properties / alternatives / description
      Added value: +"Options you considered and rejected."
    • addedInput schema / properties / decisions / items / properties / rationale / description
      Added value: +"Why you chose it."
    • addedInput schema / properties / decisions / items / properties / title / description
      Added value: +"The decision, for example Use a provider trait."
    • addedInput schema / properties / dependencies / description
      Added value: +"Intent ids (int_...) this change builds on, and the dependency list acceptance enforces. accept_changeset refuses with UNSATISFIED_DEPENDENCY unless each is ACCEPTED or COMMITTED and its accepted commit is in this change's Git history. Intent ids only: not package or library names."
    • addedInput schema / properties / files / description
      Added value: +"Changed file paths. Left empty, they are inferred from uncommitted changes only, so list them for committed work."
    • addedInput schema / properties / git_ref / description
      Added value: +"Candidate commit. Omit it: it defaults to the worktree's HEAD, and acceptance rejects any other commit with STALE_CHANGESET."
    • addedInput schema / properties / intent_id / description
      Added value: +"The intent (int_...) this implementation fulfils."
    • addedInput schema / properties / provenance / description
      Added value: +"Optional JSON object of your own context, such as a prompt or task reference. Foremerge adds Git provenance under provenance.git."
    • addedInput schema / properties / summary / description
      Added value: +"What the change does, in one or two sentences."
    • addedInput schema / properties / symbols / description
      Added value: +"Code symbols added or changed. Left empty, they are inferred from uncommitted changes only, so list them for committed work."
    • addedInput schema / properties / tests / description
      Added value: +"Tests you ran yourself. Recorded as history only; acceptance relies on run_verification, not on this list."
    • addedInput schema / properties / tests / items / properties / command / description
      Added value: +"The command you ran, for example cargo test."
    • addedInput schema / properties / tests / items / properties / status / description
      Added value: +"Its outcome as you observed it, for example passed or failed."
    • addedInput schema / properties / tests / items / properties / summary / description
      Added value: +"Optional short note on what ran or failed."
    • addedInput schema / properties / worktree / description
      Added value: +"Path of the Git worktree holding the change. Defaults to your registered worktree, then the server's working directory. Must belong to your registered repository."
  3. First observedv0.1.0

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the annotations (readOnly=false, idempotent=false, destructive=false) by disclosing the state machine: the ChangeSet starts PROVISIONAL, the intent becomes PROVISIONAL, re-publishing supersedes the old ChangeSet and resets verification. It also states the important safety fact that Git itself is not modified, plus the STALE_CHANGESET rejection behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Dense but front-loaded: the first sentence establishes purpose, the second establishes workflow position, then behavior and preconditions follow. Every sentence carries information, though the description runs long and a reader must hold several state-transition facts at once.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 13-parameter mutation tool with no output schema, the description covers preconditions, side effects, state transitions, and even the return payload ('the ChangeSet, including its chg_ id, fingerprint, and open_conflicts'). Nothing an agent needs to invoke it correctly appears to be missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already carries the parameter burden; the description's note that files and symbols are inferred only from uncommitted changes largely restates the schema's own wording. It does add the defaulting chain for worktree (registered worktree, then server CWD) and the fingerprint/base_ref resolution, but these are also documented in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Record a finished unit of implementation for your intent') and immediately positions it in the workflow relative to siblings check_conflicts, run_verification, and accept_changeset. An agent can distinguish it from get_changeset and publish_intent without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit ordering ('once the change is committed in your worktree, after check_conflicts and before run_verification') and explicit eligibility conditions ('Only the intent's owner may publish, while the intent is CLAIMED, IN_PROGRESS, PROVISIONAL or VALIDATED'). It also names the alternative path for committed work, and covers the re-publish case that selects a different outcome.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools