amicus 0.2.0__tar.gz → 0.4.0__tar.gz

{amicus-0.2.0 → amicus-0.4.0}/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "One MCP server for every second-opinion model: consult, review, and delegate with the backend as a parameter.",
   "author": { "name": "Brian Connelly", "url": "https://github.com/briandconnelly" },
   "homepage": "https://github.com/briandconnelly/amicus",

{amicus-0.2.0 → amicus-0.4.0}/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "One MCP server for every second-opinion model: consult, review, and delegate with the backend as a parameter.",
   "author": { "name": "Brian Connelly", "url": "https://github.com/briandconnelly" },
   "homepage": "https://github.com/briandconnelly/amicus",

amicus-0.4.0/.github/copilot-instructions.md

@@ -0,0 +1,42 @@
+# Copilot code review instructions
+
+Review guidance for GitHub Copilot code review in this repository.
+`AGENTS.md` holds the rules every contributor and reviewer works under; this file adds what a reviewer needs on top of it and does not restate it.
+Rule numbers below refer to the numbered list under "Rules" in `AGENTS.md`.
+Copilot reads this file from a pull request's head branch, so the pull request that changes it is reviewed under the changed version.
+
+## Rules
+
+1. When a comment enforces a numbered `AGENTS.md` rule, name the rule number.
+   A convention that only the surrounding code establishes needs no citation; describe the pattern the change breaks instead.
+2. Never propose a new or widened contract as a review fix: a tool name, parameter, description claim, error code, value enum or result envelope the pull request did not already change, or a change to the persisted result shape.
+   The surface categories are listed in `FINGERPRINT_COVERS` (`src/amicus/schemas/fingerprint.py`); a change there moves `FINGERPRINT` (rule 10), and a persisted-shape change moves `RESULT_FORMAT` (rule 11); the test that guards each pin states the commit shape it requires.
+   A new contract is a design decision, made in a milestone plan or by the maintainer, so state the concern and say that it needs a decision.
+   Do ask that a contract the pull request changes match its implementation, its plan and its stated intent; that is a correction, and it still moves the version it touches.
+3. Never propose a hand edit to a generated pin: the `*_snapshot.json` and `*_differentials.json` files under `tests/fixtures/`, or `uv.lock`.
+   The test that guards each pin names the command that regenerates it; if a pin looks wrong, say which source of truth it disagrees with.
+   `tests/fixtures/fakebackend/` is source for the wheel-seam test and is edited by hand.
+4. Before flagging a rule-18 violation, read rule 18's exemptions from `AGENTS.md` itself and check the path against them; never flag a use of one of those exemptions, and flag every path rule 18 does not exempt.
+5. For every defect, give a concrete input or sequence that produces the wrong outcome; if you cannot, label the comment a question.
+6. Do not report what a gate command reports on its own: a lint, format, type, import-boundary or test failure, or a Markdown claim that a test pins (see Context).
+7. Put one issue in each comment, and say whether it blocks merging or is optional.
+8. When a test is added or changed, check that its assertion can fail: name the change to the code under test that would turn it red, and flag the test if there is none.
+9. When prose describes code (a tool description, a docstring, a README section, `CHANGELOG.md`, an ADR), check the claim against the source in the same pull request and flag any claim the code does not bear out.
+10. Under `docs/`, flag a prose paragraph that wraps one sentence across several lines (rule 16).
+11. Under `.github/workflows/`, check the change against rules 14, 15 and 22 and name the one it breaks.
+
+## Context
+
+### What the gate already checks
+
+Rule 2 in `AGENTS.md` defines the gate; CI runs it, preceded by the Actions-pinning check (rule 3).
+Some tests pin Markdown surfaces against the code, for example `docs/MIGRATION.md`'s tool and parameter names and the README install pin; a claim one of those tests pins is gate-covered.
+Nothing in the gate checks prose style, so rule 16, stale claims no test pins and unpinned drift between documentation and code are reviewer work.
+
+### Where the risk concentrates
+
+- Rule 18 governs every path a prompt input (`INPUT_FIELDS` in `src/amicus/request.py`) can take.
+  Any new log line, error message, argv construction, fixture or committed capture that can carry one of those values is the highest-value place to look.
+- `src/amicus/jobs/delivery.py` is the chokepoint through which every stored result is delivered; a schema gap there reaches every client.
+- `scripts/check_release_state.py`, `scripts/record_live_gate_evidence.py`, `.github/workflows/publish.yml` and `docs/RELEASING.md` implement rules 19 to 24; check that a change to one keeps the others true.
+- `tests/conftest.py` carries the rule-6 guard and `tests/support/fake_codex.py` stands in for the real CLI, so a test that would only pass with a real `codex`, `kimi` or `claude` on `PATH` is a defect.

{amicus-0.2.0 → amicus-0.4.0}/.github/dependabot.yml

@@ -15,6 +15,17 @@ updates:
         dependency-type: "development"
       python-runtime:
         dependency-type: "production"
+    # pyproject.toml caps fastmcp and mcp to a minor line because fastmcp
+    # documents breaking changes in minor releases. Widening a cap is a
+    # hand-written upgrade PR (#106), so Dependabot is told not to propose the
+    # minor or major that would move it; patch releases inside the cap still
+    # arrive through the python-runtime group. `ignore` also covers security
+    # updates, which changes nothing: the cap already excludes those versions.
+    ignore:
+      - dependency-name: "fastmcp"
+        update-types: ["version-update:semver-minor", "version-update:semver-major"]
+      - dependency-name: "mcp"
+        update-types: ["version-update:semver-minor", "version-update:semver-major"]
 
   # GitHub Actions used in workflows (keeps SHA pins current).
   - package-ecosystem: "github-actions"

{amicus-0.2.0 → amicus-0.4.0}/.github/workflows/publish.yml

@@ -22,7 +22,7 @@ jobs:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+      - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
       - run: uv build
       - run: uv run --with twine twine check dist/*
       - name: The built wheel's console script must start a real MCP server
@@ -70,7 +70,7 @@ jobs:
           persist-credentials: false
           # Full history and tags: the check reads the annotated tag OBJECT, not just the ref.
           fetch-depth: 0
-      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+      - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
       - name: The tagged tree and the tag must satisfy the release predicate
         # See scripts/check_release_state.py for what a pass does and does not prove. In
         # short: the tree's release-state coherence is proven; the live-gate record carried in

{amicus-0.2.0 → amicus-0.4.0}/.github/workflows/test.yml

@@ -19,7 +19,7 @@ jobs:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+      - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
         with:
           python-version: ${{ matrix.python-version }}
           enable-cache: true
@@ -37,3 +37,20 @@ jobs:
         run: uv run lint-imports
       - name: Test (95% coverage floor)
         run: uv run pytest
+
+  marketplace-pointer:
+    name: marketplace pointer
+    # Only a pull request has a base to compare the pointer against.
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+          # Full history and tags: the pointer's tag is checked, and the base commit is read.
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+      - name: The marketplace pointer is consistent and never moves backwards
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+        run: uv run python scripts/check_release_state.py --base "$BASE_SHA"

{amicus-0.2.0 → amicus-0.4.0}/.mcp.json

@@ -4,7 +4,7 @@
       "command": "uvx",
       "args": [
         "--from",
-        "git+https://github.com/briandconnelly/amicus.git@v0.1.0",
+        "git+https://github.com/briandconnelly/amicus.git@v0.4.0",
         "amicus-mcp"
       ],
       "env_vars": [

{amicus-0.2.0 → amicus-0.4.0}/AGENTS.md

@@ -31,10 +31,11 @@ The rules bind; the context after them explains and points elsewhere.
     This binds amicus's own handling and everything it commits, including host captures and eval prompt bodies, which are recorded as an id and a `sha256` instead.
     A backend's own native carrier is exempt where that backend offers no alternative and the carrier is disclosed in its `CARRIERS` string and surfaced on `amicus_backends`; the two that exist today are Kimi's handshake file, because kimi ignores stdin, and Codex's `-c developer_instructions` argv token.
     Prompt text that a test or capture script assembles entirely from its own literals is exempt, including the `build_*_prompt` output committed in `tests/fixtures/*_differentials.json`; it stays verbatim, because a differential must show what changed and a hash cannot.
-    No exemption reaches text that was copied, derived or replayed from a prompt anyone sent: that stays bound however it is later stored or relabelled.
+    No exemption reaches text that amicus itself, or anyone working in this repository, copies, derives or replays from a prompt anyone sent: that stays bound however it is later stored or relabelled.
+    A backend's answer, and the result amicus builds from it — its parsed fields and, for a delegate, the diff captured from the worktree — is output, not a prompt input, even where it quotes or paraphrases one: amicus keeps it only on the job record (`result.json`, written through a staging file in the same directory), under the job retention the tool surface discloses (`AMICUS_JOB_TTL`, the per-workspace cap, `amicus_job_consume_result`), and writes it to no log, argv or other file; what this repository commits of an answer stays bound by the sentence before this one wherever the answer repeats a prompt anyone sent.
 19. Release in two PRs: the work lands with the version literals untouched, then a `chore(release):` PR moves them together and rolls `## [Unreleased]` in `CHANGELOG.md` into a dated section.
-    The literals are `pyproject.toml`, `src/amicus/__init__.py`, `.claude-plugin/plugin.json` and `.codex-plugin/plugin.json`.
-    `.mcp.json`'s pin is NOT one of them; rule 24 governs it, and a release must not touch it.
+    The literals are `pyproject.toml`, `src/amicus/__init__.py`, `.claude-plugin/plugin.json`, `.codex-plugin/plugin.json` and `.mcp.json`'s `--from` pin, which names the tag of the release being made; README's "Any other MCP client" example moves with that pin.
+    `.claude-plugin/marketplace.json`'s pointer is NOT one of them; rule 24 governs it, and a release must not touch it.
     `uv.lock` mirrors the version rather than declaring it: regenerate it in that same PR with `uv lock`, or the `uv lock --check` hook fails.
     Only the maintainer merges that PR, and only the maintainer pushes the tag.
     Push the matching tag before any other work follows that merge: until it exists, `main` declares a version that has no release.
@@ -47,16 +48,20 @@ The rules bind; the context after them explains and points elsewhere.
     Never move a release check into the `pypi` job: GitHub holds every step of an environment job behind that environment's required reviewer, so a check placed there runs only after the approval it exists to inform.
 23. Never describe the rule-20 record, in any document or output, as proof that the live gates ran.
     It is the maintainer's assertion, machine-checked for shape and for naming the tagged commit; the runs happen on the maintainer's machine and the record is written there.
-24. `.mcp.json`'s `--from` pin names a release that is already published, never the one being released, and it may never name a version newer than the one the tree declares.
-    A release PR under rule 19 leaves it untouched; move it to the new tag in its own `chore(release):` PR after that tag is published and its install has been checked.
+24. `.claude-plugin/marketplace.json`'s plugin entry names a release that is already published, by `ref` and a `sha` equal to that tag's peeled commit, never the one being released, and it may never name a version newer than the one the tree declares.
+    A release PR under rule 19 leaves it untouched; advance it to the new tag in its own `chore(release):` PR after that tag is published and its install has been checked, and a release is not complete until that PR merges.
     That PR is not a release: it needs no rule-20 evidence, because it moves a pointer to a tag that already exists.
+    Until the 0.4.0 pointer PR merges the entry's `source` is `"./"`; for 0.4.0 only, nothing else merges to `main` between the release PR and that pointer PR.
 
 ## Context
 
 ### What this is
 
-One MCP server for every second-opinion model: a verb-first tool surface with the backend as a parameter, built on FastMCP and the [pontonier](https://github.com/briandconnelly/pontonier) backend SDK.
+One MCP server for every second-opinion model: a verb-first tool surface with the backend as a parameter, built on FastMCP and its own in-tree backend SDK, `amicus.sdk`.
 The package is `amicus` under `src/`; each backend is a plugin under `src/amicus/backends/<id>/` behind the `BackendPlugin` seam in `src/amicus/plugin.py`.
+`amicus.sdk` (under `src/amicus/sdk/`) is the backend-facing layer: the backend protocol and contract, the error vocabulary, annotations and preflight, the subprocess runtime with stream capping, redaction, path-alias sanitizing and a bounded JSON reader, and the conformance kit a plugin must pass before the registry will use it.
+It was copied from [pontonier](https://github.com/briandconnelly/pontonier) v0.9.0, and amicus no longer depends on pontonier (ADR 0029).
+ADR 0030 holds it to that role, so what only the server uses lives in the amicus package that owns it: the job store is `amicus.jobs`, worktrees and diff gathering are `amicus.orchestration`, and the fingerprint mechanics are `amicus.schemas.fingerprint`.
 Import boundaries between layers are enforced by the import-linter contracts in `pyproject.toml`.
 A backend's own prompt carriers (for Codex, the developer-instructions argv token and the stdin prompt) are disclosed on `amicus_backends`.
 
@@ -76,12 +81,14 @@ The README's "Where things are" table indexes the rest.
 
 ### Releases
 
-`.mcp.json` pins `git+https://github.com/briandconnelly/amicus.git@v{version}`, and that pin is what a fresh plugin install actually fetches: users add this repository as a marketplace, so the manifest they read is the one on `main`.
-Rule 24 therefore keeps it naming a release that is already published rather than the one being released.
-A manifest on `main` cannot name an artifact that only exists after `main` has moved, and pinning the version under release meant every release broke a fresh install for the interval between the release merge and the tag push.
-Rule 24 removes that interval rather than shortening it.
-Two facts decided the shape, and both were established by probe rather than argued: a commit SHA resolves over the same git transport a tag does, so the install path can be rehearsed before any tag exists; and `uvx` reuses a cached tool environment without querying any index, so the version in the requirement string is what makes an existing user pick up a new release — which is why an unpinned source was rejected rather than adopted.
-0.1.0 was the bootstrap, tagged and published on 2026-09-09; it named the tag it created because no earlier release existed, and that case cannot recur.
+Users add this repository as a plugin marketplace, and a host copies the plugin into a directory keyed by `plugin.json`'s version, re-reading it only when that version changes.
+ADR 0031 is shaped by that fact, established by probe on Claude Code and Codex, and it supersedes ADR 0015, which had assumed a host re-reads `.mcp.json`.
+Under ADR 0015 the pin trailed the release, so an install taken before the pin-move PR, or anywhere mid-cycle, kept running an older server than its own skills (issue #117).
+So `.mcp.json` names its own release, and from 0.4.0 the marketplace entry pins a published tag by `ref` and `sha`, so hosts install that self-consistent tag snapshot rather than `main`.
+Until the 0.4.0 pointer PR merges, the entry is still `"./"` and hosts install `main`, which is why rule 24 bars anything else from merging during that one transition.
+Rule 24's invariant, that the pointer users follow names an already-published release, moved with it from `.mcp.json` to the marketplace entry.
+`sha` is required because a host serves `sha` over a disagreeing `ref` without complaint, and the `v*` ruleset's admin bypass means a tag can be moved.
+`uvx` reuses a cached tool environment without querying any index, so the version in `.mcp.json`'s requirement string is still what makes an existing install pick up a new server.
 Rule 20 is a local pre-tag gate rather than a CI job: hosted runners have no authenticated `codex`, `kimi` or `claude`, so the evidence is recorded on the maintainer's machine against the exact commit to be tagged.
 That evidence is an honest-mistake guard, not an attestation; it is a local file its author can write by hand.
 Rule 21 covers creation as well as update and deletion because pushing a `v*` tag is by itself what triggers `.github/workflows/publish.yml`: an identity that can create one can publish a release without rules 19 and 20 ever being satisfied, and a moved tag silently changes what users install under a version they already trust.
@@ -101,6 +108,7 @@ Those are held by the platform controls around the release — rule 21's ruleset
 ### Siblings
 
 The sibling checkouts named in rule 17 are read for porting, and their virtualenvs are used to capture differential fixtures (`scripts/capture_codex_differentials.py` runs inside codex-in-claude's).
+`~/projects/pontonier` is a sibling in the same sense: amicus no longer depends on it, its `v0.9.0` tag is where `amicus.sdk` came from, and it stays published only for the three older siblings until they are archived (ADR 0029).
 
 ### Local hooks