amicus 0.1.0__tar.gz → 0.2.0__tar.gz

{amicus-0.1.0 → amicus-0.2.0}/.agents/skills/separating-context-from-constraints/SKILL.md

@@ -1,8 +1,12 @@
 ---
-name: separating-context-from-constraints
 description: Use when auditing or reviewing a skill, system prompt, CLAUDE.md/AGENTS.md, MCP tool or resource description, slash-command prompt, or any document an AI agent consumes as instructions, to check that binding rules are separated from background context. Symptoms include rules buried mid-paragraph in narrative prose, hedged statements ("generally", "try to") that leave unclear whether they bind, untestable directives like "be concise", compound rules bundling several obligations, rule sections padded with explanation, and agents that follow a document's flavor text but miss its requirements. Produces findings with two-level severity and semantic-preserving suggested rewrites; does not score documents, analyze conflicts with parent instruction layers, or review general prose quality.
+metadata:
+    github-path: separating-context-from-constraints
+    github-ref: refs/heads/main
+    github-repo: https://github.com/briandconnelly/skills
+    github-tree-sha: 967a99232de22bc967c12a7aefcf272cfe2fb938
+name: separating-context-from-constraints
 ---
-
 # Separating Context from Constraints
 
 Audit agent-consumed instruction documents — skills, system prompts, CLAUDE.md/AGENTS.md, MCP tool and resource descriptions, slash-command prompts — for separation of binding rules from context.

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

@@ -1,8 +1,8 @@
 {
   "name": "amicus",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "One MCP server for every second-opinion model: consult, review, and delegate with the backend as a parameter.",
-  "author": { "name": "Brian Connelly" },
+  "author": { "name": "Brian Connelly", "url": "https://github.com/briandconnelly" },
   "homepage": "https://github.com/briandconnelly/amicus",
   "repository": "https://github.com/briandconnelly/amicus",
   "license": "MIT",
@@ -13,7 +13,7 @@
   "interface": {
     "displayName": "amicus",
     "shortDescription": "Consult, review, and delegate to Codex, Kimi, or Claude — one server, backend as a parameter.",
-    "longDescription": "amicus gives Claude Code one tool surface for every second-opinion model. Pick the backend as a parameter instead of installing a server per model. Delegation runs in a throwaway git worktree and returns a reviewable diff that is never applied to your working tree. Long jobs run asynchronously with a job id you can poll, cancel, and recover. Enabling a backend that can write makes every tool carry that backend's approval annotations — see docs/MIGRATION.md.",
+    "longDescription": "amicus gives Claude Code one tool surface for every second-opinion model. Pick the backend as a parameter instead of installing a server per model. Delegation runs in a throwaway git worktree and returns a reviewable diff that is never applied to your working tree. Long jobs run asynchronously with a job id you can poll, cancel, and recover. Enabling a backend that can write makes every tool carry that backend's approval annotations — see https://github.com/briandconnelly/amicus/blob/main/docs/MIGRATION.md.",
     "developerName": "Brian Connelly",
     "category": "Developer Tools",
     "capabilities": ["MCP", "Skills"],

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

@@ -1,8 +1,8 @@
 {
   "name": "amicus",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "One MCP server for every second-opinion model: consult, review, and delegate with the backend as a parameter.",
-  "author": { "name": "Brian Connelly" },
+  "author": { "name": "Brian Connelly", "url": "https://github.com/briandconnelly" },
   "homepage": "https://github.com/briandconnelly/amicus",
   "repository": "https://github.com/briandconnelly/amicus",
   "license": "MIT",
@@ -12,7 +12,7 @@
   "interface": {
     "displayName": "amicus (for Codex)",
     "shortDescription": "Consult, review, and delegate to Codex, Kimi, or Claude — one server, backend as a parameter.",
-    "longDescription": "amicus gives Codex one tool surface for every second-opinion model. Pick the backend as a parameter instead of installing a server per model. Delegation runs in a throwaway git worktree and returns a reviewable diff that is never applied to your working tree. Long jobs run asynchronously with a job id you can poll, cancel, and recover. Enabling a backend that can write makes every tool carry that backend's approval annotations — see docs/MIGRATION.md.",
+    "longDescription": "amicus gives Codex one tool surface for every second-opinion model. Pick the backend as a parameter instead of installing a server per model. Delegation runs in a throwaway git worktree and returns a reviewable diff that is never applied to your working tree. Long jobs run asynchronously with a job id you can poll, cancel, and recover. Enabling a backend that can write makes every tool carry that backend's approval annotations — see https://github.com/briandconnelly/amicus/blob/main/docs/MIGRATION.md.",
     "developerName": "Brian Connelly",
     "category": "Developer Tools",
     "capabilities": ["MCP", "Skills"],

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

@@ -33,10 +33,11 @@ The rules bind; the context after them explains and points elsewhere.
     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.
 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`, `.codex-plugin/plugin.json` and the `.mcp.json` tag pin.
+    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.
     `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 immediately after that merge, before any other work: the interval in which `main` names a tag that does not yet exist cannot be made zero, so closing it is the only task that may follow the merge.
+    Push the matching tag before any other work follows that merge: until it exists, `main` declares a version that has no release.
 20. Never push a `v*` tag unless the three live gates — `tests/test_codex_live.py`, `tests/test_kimi_live.py` and `tests/test_claude_live.py`, run under rule 5 — have all PASSED on that exact commit, with those passing outcomes recorded.
     The record is `.release-evidence/live-gates.json`, written by `scripts/record_live_gate_evidence.py`, naming that commit, each suite and its outcome; a terminal transcript or a recollection is not a record.
     A record showing a failed suite does not satisfy this rule; it is a reason not to tag.
@@ -46,6 +47,9 @@ 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.
+    That PR is not a release: it needs no rule-20 evidence, because it moves a pointer to a tag that already exists.
 
 ## Context
 
@@ -72,21 +76,26 @@ The README's "Where things are" table indexes the rest.
 
 ### Releases
 
-Rules 19 and 20 exist because `.mcp.json` pins `git+https://github.com/briandconnelly/amicus.git@v{version}`.
-Until the matching tag exists, a plugin install from `main` fails on an unresolvable ref.
-That window opens at every release and cannot be eliminated, because merging and tagging are separate operations; rule 19's last clause keeps it to the seconds between them rather than removing it.
-`main` carries exactly that unresolvable pin today, because 0.1.0 has never been tagged, and the first release closes this instance of it.
+`.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.
 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.
-No such ruleset exists yet, so rule 21 currently forbids tagging; creating it is a maintainer prerequisite of the first release, and `docs/RELEASING.md` reads it back rather than assuming it.
+That ruleset now exists — `release tags`, active, covering `refs/tags/v*` and restricting creation, update and deletion — and 0.1.0 was tagged under it.
+Its bypass list is the part an agent here cannot check: the ruleset response seen from this repository's agent token carries no `bypass_actors` key at all.
+GitHub omits that key from responses to requesters without sufficient permission on the ruleset rather than returning an empty list, so its absence is not evidence that nobody may bypass, and must never be reported as though it were.
+`docs/RELEASING.md` reads that back with the maintainer's own token rather than assuming it.
 The executable procedure — preconditions, the evidence run, the environment approval pause and the post-tag checks — is `docs/RELEASING.md`.
 
 Rules 20, 22 and 23 are shaped by what a CI job can and cannot establish, which is the subject of ADR 0014 and of issue #25 before it.
 The `verify` job runs `scripts/check_release_state.py` on the tagged commit, and the two halves of that script are worth different amounts.
 Its release-state coherence half **proves** what it reports: every version literal rule 19 names, the dated `CHANGELOG.md` section, and `uv.lock` are all facts of the tagged tree.
 Its live-gate half checks only that the record carried on the tag is well formed, names this commit and asserts three passing suites — never that those suites ran, which is why rule 23 forbids saying otherwise.
-Everything else rule 19 requires is a convention no CI job can prove: two PRs, an ordinary merge commit rather than a squash, the maintainer merging rather than an agent, and the tag pushed before any other work.
+Everything else rule 19 requires is a convention no CI job can prove: two PRs, an ordinary merge commit rather than a squash, the maintainer merging rather than an agent, and the tag pushed promptly after the merge.
 Those are held by the platform controls around the release — rule 21's ruleset and the `pypi` environment's required reviewer — and by whoever runs the procedure, and this repository states that plainly rather than implying the workflow checks it.
 
 ### Siblings

amicus-0.2.0/CHANGELOG.md

@@ -0,0 +1,226 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-09-10
+
+Across this release the discovery surface moves `amicus/0.1/schema-7` -- what 0.1.0 shipped -- to
+`amicus/0.1/schema-13`, and stored job results move `RESULT_FORMAT` 2 to 4. The entries below are
+per-change rather than net, so they also name intermediate states that no release ever shipped:
+`schema-8` through `schema-12`, and `RESULT_FORMAT` 3.
+
+### Changed
+
+- **Breaking (`FINGERPRINT` `schema-13`).** The discovery catalog now advertises a real
+  SEP-2549 freshness window instead of the SDK's `ttlMs: 0`. `server/discover`,
+  `tools/list`, `resources/list`, `resources/templates/list` and `prompts/list` carry
+  `ttlMs: 300000`, `cacheScope: private`; those records are fixed for the life of the
+  process, so a modern client that opts into caching no longer re-walks 99,053 bytes of
+  `tools/list` to learn nothing changed. `resources/read` deliberately carries no hint and
+  stays at `ttlMs: 0`: the SDK chooses a hint per method while the client keys its cache
+  per URI, and `amicus://backends/{backend}` and `amicus://models/{backend}` report live
+  install, auth and model-catalog state. `tools.listChanged` and `resources.listChanged`
+  now report `false` on the handshake era too, matching the modern era and matching
+  amicus, which has no `notifications/*/list_changed` emission site -- the handshake `true`
+  came from FastMCP's hardcoded `NotificationOptions` and promised a notification that
+  could not arrive. The committed manifest also pinned
+  `initialize.capabilities.resources.listChanged: true`, a value the shipped stdio
+  transport never sent, because it is built over the in-memory transport; both eras'
+  capabilities are now asserted against a real `amicus-mcp` subprocess. `RESULT_FORMAT`
+  stays `4`. `surface_digest` moves only because `instructions` gained a clause naming it
+  as the catalog re-read check: revert that clause and the digest returns to its previous
+  value, because the digest covers the catalog records as the server holds them (before
+  response middleware) plus `instructions`, and not the capability blocks or the cache
+  envelope. The cache hints are inert for both captured hosts, which negotiate the
+  handshake era; the `listChanged` flip is not, and is visible to exactly those clients. Supersedes ADR 0006's cache-hint clause; see
+  ADR 0018. (#45)
+- **Breaking (`FINGERPRINT` `schema-12`).** The published stability tier is now inside the
+  closed set an agent can filter on. Nine of the 18 tools -- the ones absent from the per-tool
+  override table -- carried `alpha` in their lifecycle `_meta`, as did all four static resources
+  and both resource templates, and `amicus_capabilities.stability` reported it too:
+  a value outside both `[9.stability-tiers]`'s `stable | preview | experimental` and amicus's
+  own `ToolStability` literal, so a caller filtering on the tier could not interpret it. The
+  server-wide tier is now `experimental`, the honest one for a 0.1.x surface and already the
+  tier the four `_async` and five `amicus_job_*` tools declared; their per-tool overrides are
+  gone, and `amicus_capabilities.tool_details[].stability` is `null` for all 18 tools, which
+  means what it always meant -- inherit the top-level tier. `stability` is also published as
+  the three-value enum rather than a bare string, so an illegal tier now fails assembly
+  instead of reaching a caller. `RESULT_FORMAT` stays `4`: no stored result carries a tier.
+  tools/list grows 106 bytes and the discovery-cost ratchet is raised deliberately
+  (`tests/test_discovery_cost.py` says what the bytes buy).
+- `FINGERPRINT` moves `amicus/0.1/schema-10` → `amicus/0.1/schema-11` for the scoped
+  `workspace_root` prerequisite, which changes `initialize_response` and `capabilities_payload`,
+  with every pin regenerated in a dedicated commit (rule 10). `RESULT_FORMAT` stays `4`: no stored
+  result changed shape, and no `inputSchema` changed, so the discovery-cost ratchet does not move.
+- **Breaking (`FINGERPRINT` `schema-10`, `RESULT_FORMAT` 4).** `confidence` on a review or
+  adversarial-review result gained a fourth value, `unknown`, and both tools now publish what the
+  field means. `unknown` is the ABSENCE of a rating -- the backend supplied none amicus could
+  read, and the verdict was not withheld either -- never a low one. amicus substitutes `low`
+  only where it also withholds the verdict as `unknown` -- partial coverage, findings it could
+  not carry, or a `not_run` review -- so a `low` beside any other verdict is the backend's own
+  word, and a high confidence is never evidence that coverage was complete. Backends are still asked for `low|medium|high`; the new value is amicus's, not
+  theirs. A `RESULT_FORMAT` 3 reader's closed enum rejects a stored result
+  carrying it.
+- **Breaking (`FINGERPRINT` `schema-9`, `RESULT_FORMAT` 3).** Every consult, review,
+  adversarial-review and delegate result gained `findings_diagnostics`: `null` when nothing was
+  lost, otherwise a `dropped` count and reasons from a fixed vocabulary
+  (`severity_normalized`, `extra_fields_omitted`, `invalid_entry`, `invalid_container`,
+  `missing_findings`). Read the
+  reasons rather than the count: `dropped` counts whole entries, so a `0` beside
+  `extra_fields_omitted` still means content was lost, and a `null` means the count was
+  unknowable, never that nothing was lost.
+- A job result stored under a different `result_format` is now rejected before validation rather
+  than after it. It used to pass, because a field added since it was written validates from its
+  own default -- and that default would have asserted, on the producing run's behalf, that no
+  finding was lost on a run that never measured loss.
+- `FINGERPRINT` moves `amicus/0.1/schema-7` → `amicus/0.1/schema-8` for the `amicus_job_result`
+  description change, with every pin regenerated in a dedicated commit (rule 10).
+  `RESULT_FORMAT` did not move for it: no stored result changed shape.
+- `SKILL.md`'s rule block is now the complete contract: ten obligations that lived in explanatory
+  prose moved into labelled rules, and the facts that motivate them moved to an adjacent
+  `Semantics` section ([ADR 0016](docs/adr/0016-skill-rules-are-a-complete-contract.md)).
+- The returned-diff response contract separates the assessment of a proposal
+  (`Verdict: accept | reject | cannot-assess`) from the action taken on the working tree
+  (`Action: applied | not applied`). S6's recorded pass was graded against the superseded contract
+  and is not carried forward as a pass against the new one.
+- Both plugin manifests carry `author.url`, and their `longDescription` names
+  `docs/MIGRATION.md` by absolute URL rather than by a repository-root-relative path that
+  does not resolve for a consumer who vendors the manifest without the repository around it.
+- `.mcp.json`'s pin now names an already-published release rather than the version being
+  released, so `main` never sends a fresh install to a tag that does not exist yet
+  ([ADR 0015](docs/adr/0015-mcp-json-pins-an-already-published-release.md), issue #26).
+  The pin is no longer a release version literal; a small `chore(release):` PR moves it after the
+  tag is pushed.
+- `scripts/check_release_state.py` replaces its `pin == version being released` equality — which was
+  true by construction on any tree a release PR had touched — with a shape check, a check that the
+  pin never leads the release, and a check that the pinned tag actually exists.
+- `docs/RELEASING.md` gains a pre-tag install rehearsal that runs the committed manifest's own
+  command against the release commit's SHA, so git transport, a clean-machine build and the wire
+  handshake are all exercised before anything irreversible happens.
+- The README's status section describes 0.2.0 rather than 0.1.0, and names the surface and
+  stored-result moves a client upgrading across this release has to account for.
+
+### Fixed
+
+- The published prerequisite no longer sends a sessionless client's first call into an
+  `invalid_arguments` error (issue #40). Both the server `instructions` and
+  `amicus_capabilities.prerequisites` told a sessionless (2026-07-28) client to pass
+  `workspace_root` on EVERY call, and the same `instructions` name `amicus_backends` as the call
+  to make before the first paid one. `amicus_backends`, `amicus_models` and `amicus_capabilities`
+  declare no `workspace_root`, and every `inputSchema` is `additionalProperties: false`, so an
+  agent that followed the prerequisite failed at exactly the call the instructions told it to make
+  first. The prerequisite was correct for the other fifteen tools, so it is scoped to the calls
+  that declare the parameter, and both surfaces now render one shared sentence built from
+  `WORKSPACELESS_TOOLS` rather than each stating the rule in its own words; the
+  `invalid_workspace_root` repair carried the same "every call" wording and is scoped with it. A
+  manifest test binds that tuple to the live schemas, probes that each named tool really does
+  reject `workspace_root`, and requires every surface stating the prerequisite to carry the shared
+  sentence and no other workspace_root claim. What is machine-checked is the tool set and the
+  single source, not the prose: one sentence is what a reviewer has to read, and it can no longer
+  disagree with the schemas or with itself.
+
+- Exception text no longer reaches the diagnostic log, on any path (issue #39). AGENTS.md rule 18
+  forbids writing a prompt input to a log, and an exception raised inside a backend adapter can
+  embed the text that provoked it. Two carriers did exactly that: the unexpected-exception guard
+  logged with `.exception()`, whose rendered traceback carries the original exception's `str()`,
+  and its own message interpolated `exc_summary(exc)` -- which masks secrets and control
+  characters, not prompt inputs, so it was never the safe form the guard's comment claimed. A
+  third call site, the task-map write warning in `amicus.jobs.lifecycle`, interpolated
+  `exc_summary` the same way; its `OSError` carries a path rather than a prompt, so it was a
+  latent instance of the pattern rather than a demonstrated leak, and it is gone too. Every
+  handler `amicus.obs` installs now renders under one policy: exception types and source
+  locations, never message text, notes, or source lines. The policy lives at the handler rather
+  than the call site because `pontonier`'s own runtime logs exceptions through these handlers too.
+  It is not a claim that no prompt input can ever be logged -- a call site that interpolates a
+  prompt field itself still would -- only that the exception-text family is closed.
+
+- An unreadable `confidence` no longer defaults UPWARD to `medium` (issue #53). A backend that
+  returned nothing amicus could read about its own certainty was delivered as moderately
+  confident, with nothing in the envelope to say the value had been invented -- the same
+  direction of dishonesty as issue #38, on a different field. It now falls to `unknown`. `low`
+  was not the fix: it is the lowest rating a backend can REPORT, so defaulting to it would
+  manufacture a claim too. The verdict beside it is untouched, so a backend that reported `fail`
+  and said nothing readable about its certainty is delivered as `fail`/`unknown`.
+- Review findings are no longer discarded in silence while the verdict survives (issue #38). A
+  finding that failed validation was dropped with no count and no warning, so a backend could
+  report a real problem and the caller receive an apparently clean review. Only `codex` is held
+  to the output schema natively; `claude` and `kimi` are merely asked for it in the prompt, so an
+  added `category` key or a shouted `"HIGH"` was an ordinary return that cost the whole finding.
+  Findings now survive case-normalization and unknown keys, anything still unrepresentable is
+  counted and named, and a `pass` no longer stands over a loss -- it is delivered as
+  `unknown`/`low`, while a `fail` or `concerns` keeps its verdict and its confidence.
+
+- `collaborating-with-amicus` no longer tells an agent that delegate runs have no network egress.
+  That holds for `codex`, whose sandbox amicus pins to `network_access=false`; it is false for
+  `kimi`, which has no sandbox at all. The skill now states containment per backend
+  ([ADR 0016](docs/adr/0016-skill-rules-are-a-complete-contract.md)).
+- The skill's async recipe no longer polls terminal jobs forever. `poll_after_ms` is `null` on
+  every terminal status and a cancelled job reports `result_available: false`, so the loop is now
+  driven by `status == "running"`.
+- The server's own waiting instructions now terminate too. The `job_running` repair, the
+  `follow_up` every `*_async` start returns, and `amicus_job_result`'s description all told an
+  agent to wait for `result_available`, a flag that never flips for a `cancelled`, `failed` or
+  `timeout` job. All three now gate the wait on `status` and name the terminal path, so the
+  machine-readable repair agrees with the lifecycle and with the skill (issue #35).
+- `amicus_job_result`'s description no longer tells callers to branch on `tool` unconditionally.
+  A stored error is delivered as an `ErrorResult`, which carries no `tool`, so `ok` is what to
+  check first.
+- The skill no longer claims a timed-out synchronous call costs the same quota as a completed one.
+  Amicus is not told what a terminated call cost; the reason to prefer `_async` is that a sync
+  timeout destroys the result.
+- Result guidance no longer stops at `ok`, `verdict` and `diff`. `review_status: not_run`,
+  `meta.truncated`, `meta.redacted_paths`, `meta.security_warnings` and `meta.compat_warnings`
+  all change what a result means, and `diffstat` is computed before redaction and truncation, so
+  it is not an integrity check on the returned `diff`.
+- Rule 5 no longer requires naming the backend whose annotation caused an approval prompt — an
+  attribution a host does not supply. It now separates the observed prompt from the annotation
+  policy. `effects` is documented as the static per-backend declaration it is, not "call-specific
+  truth".
+- The README's verb matrix no longer reads as a claim about what the models can do. A `no` there is
+  amicus's routing decision: `delegate` is absent on Claude by a review-only policy, and
+  `adversarial_review` is scoped to Claude for v1. The verb itself is amicus's own — the prompt it
+  builds and the result shape it returns are amicus's for any backend, with Claude contributing a
+  critic stance on top — so Codex and Kimi can review adversarially. The README now says so, points
+  at `consult` and `review_changes` for it, and names what the verb adds over them (issue #23).
+
+### Added
+
+- `collaborating-with-amicus` gains `reading-results.md`, `active-workflows.md`,
+  `options-and-errors.md`, `independent-attempt.md`, `review-revise.md` and
+  `server-down-fallback.md`. Backend selection now covers what each backend can actually inspect —
+  `claude` defaults to `access="toolless"` and cannot read the repository unless asked — and git
+  scope, brief preparation, and `idempotency_key` recovery are documented.
+- Six prospective scenarios (S9–S14) covering git scope, terminal-job lifecycle, coverage
+  reporting, backend evidence, delegate containment, and independent-attempt ordering. Schema
+  validity now binds every described call in every scenario.
+
+## [0.1.0] - 2026-09-08
+
+### Added
+
+- One MCP server for three second-opinion backends — `codex`, `kimi` and `claude` — with the backend as a tool parameter rather than a separate server (M0–M4).
+- Synchronous verbs: `amicus_consult`, `amicus_review_changes`, `amicus_delegate`, `amicus_adversarial_review`, plus free dry-run previews for review (`amicus_dry_run`) and delegate (`amicus_delegate_dry_run`).
+- Discovery surface: `amicus_backends`, `amicus_capabilities`, `amicus_models`, and the MCP resources that back them.
+- A jobs surface: `_async` twins of the paid verbs, `amicus_job_status`, `amicus_job_result`, `amicus_job_consume_result`, `amicus_job_list`, `amicus_job_cancel`, with idempotency keys, restart survival and task-id lookup (M2).
+- `task=True` on the four paid synchronous tools behind the `AMICUS_TASKS` flag (M5).
+- Packaging for both hosts: a `.claude-plugin/` manifest, a `.codex-plugin/` manifest, an `amicus-mcp` console script, and the `collaborating-with-amicus` skill (M6).
+- Release automation: a tag- and dispatch-triggered publish workflow with trusted publishing to TestPyPI and PyPI.
+- A release predicate gating that upload: a `verify` job runs `scripts/check_release_state.py` against the tagged commit, and `pypi` depends on it (issue #25, ADR 0014). It proves the tagged tree's release-state coherence — every version literal, the dated changelog section, `uv.lock` — and checks that the live-gate record carried in the annotated tag's message is well formed and names that commit. That record remains the maintainer's assertion, never proof the live gates ran.
+
+### Fixed
+
+- `record_live_gate_evidence.validate` accepted a record that omitted `batch_id` from every backend entry, so the "one shared run produced this record" property it documented was not actually checkable. `batch_id` is now a required backend field.
+
+### Known limitations
+
+- The tagged publish path to pypi.org has never run. Only the TestPyPI dispatch path has been exercised.
+- Eval scenario S6 in `skills/collaborating-with-amicus/tests/scenarios.md` passed on one run (status: `pass`, validated by that run alone); an M7 follow-up run against the current skill text did not isolate the still-open F3 finding, so F3 remains open. S7 (real-host approval friction) has failed both of its recorded runs (status: `fail`); an M7 zero-spend recheck reached neither a pass nor a fail and is recorded as inconclusive, so it does not move S7's status. See their `status` fields and ADR 0012.
+
+[Unreleased]: https://github.com/briandconnelly/amicus/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/briandconnelly/amicus/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/briandconnelly/amicus/releases/tag/v0.1.0

{amicus-0.1.0 → amicus-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: amicus
-Version: 0.1.0
+Version: 0.2.0
 Summary: One MCP server for every second-opinion model: consult, review, and delegate with the backend as a parameter
 Project-URL: Homepage, https://github.com/briandconnelly/amicus
 Project-URL: Repository, https://github.com/briandconnelly/amicus
@@ -66,8 +66,8 @@ Start a new session afterwards so the host loads the bundled skill and tools.
 
 ### Any other MCP client
 
-The plugins launch the server from the release tag pinned in [`.mcp.json`](.mcp.json). Point your
-client at the same command:
+The plugins launch the server from a published release tag, pinned in
+[`.mcp.json`](.mcp.json). Point your client at the same command:
 
 ```json
 {
@@ -132,6 +132,14 @@ Not every backend does everything:
 | `delegate` | yes | yes | no |
 | `adversarial_review` | no | no | yes |
 
+A `no` is amicus's routing decision, not a claim about the model. `delegate` is absent on Claude
+by a deliberate review-only policy. `adversarial_review` is scoped to Claude for v1, but the verb
+is amicus's own: the prompt it builds and the result shape it returns are amicus's for any
+backend, and what Claude contributes is a critic stance layered on top. So nothing about
+Codex or Kimi stops either from reviewing adversarially — ask them through `consult` or
+`review_changes` and supply the adversarial stance yourself. What the verb adds is that stance
+fixed, plus its `target` and `evidence` carriers.
+
 Asking a backend for something it does not support returns a `feature_unsupported` error naming
 the backend and the feature, rather than failing obscurely.
 
@@ -160,11 +168,12 @@ the new ones.
 
 ## Status and known limits
 
-0.1.0 is the first release. The server's wire contract is exercised by the test suite and by host
-captures against Claude Code and Codex, but:
+0.2.0 is the current release, and it is a breaking one: the discovery surface moved from
+`amicus/0.1/schema-7` to `amicus/0.1/schema-13` and stored job results from `RESULT_FORMAT` 2 to
+`4`. [`CHANGELOG.md`](CHANGELOG.md) says what moved and what a cached client should re-read. The
+server's wire contract is exercised by the test suite and by host captures against Claude Code and
+Codex, but:
 
-- 0.1.0 is the first release published from a tag, so the tagged publish path runs for the first
-  time with it.
 - Two router-skill evaluation scenarios are unresolved — S6 (diff-safety wording) and S7 (approval
   friction) — recorded in [`docs/adr/0012-m6-packaging-decisions.md`](docs/adr/0012-m6-packaging-decisions.md).
   Neither is a defect in the server's wire contract.

{amicus-0.1.0 → amicus-0.2.0}/README.md

@@ -36,8 +36,8 @@ Start a new session afterwards so the host loads the bundled skill and tools.
 
 ### Any other MCP client
 
-The plugins launch the server from the release tag pinned in [`.mcp.json`](.mcp.json). Point your
-client at the same command:
+The plugins launch the server from a published release tag, pinned in
+[`.mcp.json`](.mcp.json). Point your client at the same command:
 
 ```json
 {
@@ -102,6 +102,14 @@ Not every backend does everything:
 | `delegate` | yes | yes | no |
 | `adversarial_review` | no | no | yes |
 
+A `no` is amicus's routing decision, not a claim about the model. `delegate` is absent on Claude
+by a deliberate review-only policy. `adversarial_review` is scoped to Claude for v1, but the verb
+is amicus's own: the prompt it builds and the result shape it returns are amicus's for any
+backend, and what Claude contributes is a critic stance layered on top. So nothing about
+Codex or Kimi stops either from reviewing adversarially — ask them through `consult` or
+`review_changes` and supply the adversarial stance yourself. What the verb adds is that stance
+fixed, plus its `target` and `evidence` carriers.
+
 Asking a backend for something it does not support returns a `feature_unsupported` error naming
 the backend and the feature, rather than failing obscurely.
 
@@ -130,11 +138,12 @@ the new ones.
 
 ## Status and known limits
 
-0.1.0 is the first release. The server's wire contract is exercised by the test suite and by host
-captures against Claude Code and Codex, but:
+0.2.0 is the current release, and it is a breaking one: the discovery surface moved from
+`amicus/0.1/schema-7` to `amicus/0.1/schema-13` and stored job results from `RESULT_FORMAT` 2 to
+`4`. [`CHANGELOG.md`](CHANGELOG.md) says what moved and what a cached client should re-read. The
+server's wire contract is exercised by the test suite and by host captures against Claude Code and
+Codex, but:
 
-- 0.1.0 is the first release published from a tag, so the tagged publish path runs for the first
-  time with it.
 - Two router-skill evaluation scenarios are unresolved — S6 (diff-safety wording) and S7 (approval
   friction) — recorded in [`docs/adr/0012-m6-packaging-decisions.md`](docs/adr/0012-m6-packaging-decisions.md).
   Neither is a defect in the server's wire contract.

{amicus-0.1.0 → amicus-0.2.0}/docs/RELEASING.md

@@ -72,7 +72,8 @@ This is configured on PyPI's own project settings page and has no read-only API
 Trademark clearance for the name `amicus` is resolved, or the maintainer has decided to proceed without it.
 This was decided on 2026-09-08: `docs/adr/0013-proceed-without-trademark-clearance.md` records the decision to publish without clearance, the consequences accepted, and what would reopen it.
 Read that ADR rather than relying on anyone's recollection, and confirm nothing listed under "What would reopen this" has since happened.
-TestPyPI already has the name claimed under this project; pypi.org does not yet have a release.
+TestPyPI has the name claimed under this project, and pypi.org has carried a release since 0.1.0 was published on 2026-09-09.
+The name is therefore established on both indexes; this precondition is about clearance, not about claiming the name.
 
 ### The README describes the released tool
 
@@ -86,7 +87,9 @@ Second, its "Status and known limits" section must not claim anything the releas
 
 Rules 19 and 20 together shape this sequence, and a future maintainer should not "simplify" it back.
 Rule 20 requires the live-gate evidence to cover the exact commit being tagged.
-Rule 19 requires the tag push to be the only work that follows the PR C merge, because the interval in which `main` names a tag that does not yet exist cannot be made zero, only closed as fast as possible.
+Rule 19 requires the tag push to be the only work that follows the PR C merge, so that `main`'s version literals and the published tag agree without a gap.
+Since ADR 0015 that promptness is no longer about a broken install path: `.mcp.json` pins the newest **already-published** release, so `main` never sends a fresh install to a tag that does not exist.
+The single exception was the first release, which had no earlier tag to name; 0.1.0 was tagged and published on 2026-09-09, which closed that window permanently.
 The tag does not have to point at `main`'s head; it has to point at the commit the evidence covers.
 An ordinary merge commit keeps the PR C branch tip in `main`'s history as one of the merge commit's two parents, so tagging that branch tip is legitimate, and it is exactly the commit the evidence names — no fast-forward or branch-protection change is required to satisfy both rules.
 The tag therefore deliberately points at a commit that is in `main`'s history but is not `main`'s head, and the checks in step 5 below prove the two commits' trees are identical.
@@ -94,8 +97,14 @@ The tag therefore deliberately points at a commit that is in `main`'s history bu
 1. Merge PR B (the milestone work, version literals untouched).
 2. Open PR C, the `chore(release):` PR described by AGENTS.md rule 19, and do not merge it yet.
    Roll `## [Unreleased]` in `CHANGELOG.md` into a dated `## [X.Y.Z] - YYYY-MM-DD` section, and leave a fresh empty `## [Unreleased]` above it.
+   That date is **UTC** (`date -u +%F`), not the local date of whoever prepares the PR.
+   The two disagree for part of every day in this maintainer's timezone, and the tag, the publish run and the PyPI record are all stamped in UTC, so a local date makes the changelog disagree with every other artifact of the same release.
+   0.1.0 predates this convention and is dated `2026-09-08`, its local date; it was tagged on 2026-09-09 UTC, and that section is left as it shipped rather than rewritten.
    Change no version literal unless the version itself is changing.
-   For 0.1.0 no literal moves: `pyproject.toml`, `src/amicus/__init__.py`, both `plugin.json` files, and `.mcp.json`'s `@v0.1.0` pin already agree, and the tag is what makes that pin resolve.
+   The literals are `pyproject.toml`, `src/amicus/__init__.py` and both `plugin.json` files.
+   Do **not** touch `.mcp.json`: per ADR 0015 its pin names an already-published release, so during this PR it correctly trails the version being released by one, and step 7 moves it after the tag exists.
+   0.1.0 was the bootstrap: no literal moved, and its `@v0.1.0` pin named the tag that release itself created, because no earlier release existed.
+   That case is closed and does not recur.
    Regenerate `uv.lock` with `uv lock` in this same PR, per AGENTS.md rule 19 — `uv.lock` mirrors the version rather than declaring it, and `prek.toml`'s `uv-lock-check` hook runs `uv lock --check` whenever `pyproject.toml` changes, so a release PR that skips this fails its own hook.
 3. Check out the PR C branch tip (not `main`) into a clean tree and confirm `git status --porcelain` is empty.
    Record the branch tip's SHA; call it the release commit, and note it well — it is the commit that gets tagged, and it will not be `main`'s head after the next step.
@@ -107,6 +116,18 @@ The tag therefore deliberately points at a commit that is in `main`'s history bu
    Run `AMICUS_RELEASE_CHECK=1 uv run pytest tests/test_release_evidence.py -v --no-cov` and confirm the freshness assertion passes.
    Run `uv run python scripts/check_release_state.py` and confirm it prints `release predicate holds`.
    That is the same tree check the `verify` job will run after the tag is pushed, so a failure here is a failure you would otherwise discover with an immutable tag already in place.
+   Rehearse the real install path against the release commit, which is the check that used to be impossible before the tag existed:
+
+   ```sh
+   printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"rehearsal","version":"0"}}}' \
+     | UV_CACHE_DIR="$(mktemp -d)" uvx --from "git+https://github.com/briandconnelly/amicus.git@<release-sha>" amicus-mcp
+   ```
+
+   Substitute the release commit's SHA for the tag and change nothing else: a commit SHA resolves over the same git transport a tag does, and it exists before the tag does.
+   A clean `UV_CACHE_DIR` is what makes this mean anything — `uvx` reuses a cached tool environment without contacting any index, so a warm cache can answer from a build you already had.
+   Confirm the server answers `initialize` with `serverInfo.name == "amicus"` and the version being released.
+   This proves git transport, a clean-machine build, the console script and the wire handshake before anything irreversible happens.
+   What it does not prove is that the string `vX.Y.Z` resolves, which is the trivial remainder and is covered by the post-tag checks.
    Run the gate defined by AGENTS.md rule 2.
    The 24-hour freshness window this evidence carries (`validate`'s `max_age_hours`) is checked only here, at step 3, and deliberately not by CI afterward: a tag is immutable, so a window applied after tagging could let queue time or a slow deployment approval turn a legitimate tag into one that can never be published.
    The window is therefore yours to honor: merge PR C, the next step, before the day is out — otherwise this step must be repeated.
@@ -136,6 +157,13 @@ The tag therefore deliberately points at a commit that is in `main`'s history bu
    `--cleanup=verbatim` keeps the JSON byte-for-byte; the default cleanup would also parse, but exactness is free here.
    Confirm before pushing that `git cat-file -t vX.Y.Z` prints `tag` (not `commit`, which would mean a lightweight tag) and that `git tag -l --format='%(contents)' vX.Y.Z | python -c 'import json,sys; json.load(sys.stdin)'` exits 0.
    Nothing but step 5's read-only checks happens between step 4 and step 6.
+7. Once the publish has completed and the post-tag checks below have passed, open a small `chore(release):` PR that moves `.mcp.json`'s pin to `vX.Y.Z`.
+
+   This is the pin-move PR that ADR 0015 makes part of every release, and it is deliberately *after* the tag rather than before it: the pin names a release that already exists, so moving it earlier would be the very thing ADR 0015 removes.
+   It touches `.mcp.json` and nothing else, it is not a release under rule 19, and it needs no live-gate evidence — it moves a pointer to a tag that is already published.
+   Until it merges, `main` sends a fresh install to the previous release, which works.
+   That is the intended degradation, so do not treat it as an outage or rush the PR through without its checks.
+   This step did not apply to 0.1.0, whose pin already reads `@v0.1.0` for the bootstrap reason above; 0.2.0 is the first release to perform it.
 
 A maintainer who instead wants the tag to be `main`'s own head has a permitted alternative: a direct fast-forward push of the PR C branch to `main` (`git checkout main && git merge --ff-only <pr-branch> && git push origin main`) achieves that, if this repository's branch protection allows a direct push to `main`.
 This runbook cannot say whether it does: `gh api repos/briandconnelly/amicus/branches/main/protection` returned `403 Resource not accessible by integration` to the token available while writing it, so that setting is unverified here, and this document does not assert it either way.
@@ -171,12 +199,16 @@ They confirm the release actually landed; they are not a pre-tag gate.
 2. Install from the public tag exactly as a user would, using the committed manifest's own source:
 
    ```sh
-   uvx --from git+https://github.com/briandconnelly/amicus.git@vX.Y.Z amicus-mcp
+   printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"post-tag","version":"0"}}}' \
+     | UV_CACHE_DIR="$(mktemp -d)" uvx --from "git+https://github.com/briandconnelly/amicus.git@vX.Y.Z" amicus-mcp
    ```
 
-   Drive it with one JSON-RPC `initialize` request over stdin and assert `serverInfo.name == "amicus"` and the expected version.
-   This is the first and only check that the `.mcp.json` pin actually resolves; it cannot be run before the tag exists.
+   Assert `serverInfo.name == "amicus"` and the expected version in the reply.
+   The fresh `UV_CACHE_DIR` is part of the command, not a note beside it: a warm cache answers without resolving anything, so a copy-pasted command without it can pass while proving nothing.
+   Step 3's rehearsal already proved transport, build and handshake against the release commit's SHA, so what this adds is narrow but real — that the tag *ref* resolves, which is all that separated the rehearsal from the thing itself.
+   This is what step 7's pin-move PR is waiting on: do not move the pin to a tag whose install you have not just run.
 3. Run a negative control: the same command against a version that does not exist must fail.
+   Without it, a warm cache or a silently-substituted binary would make check 2 pass no matter what.
 
 ## Rollback
 

{amicus-0.1.0 → amicus-0.2.0}/docs/adr/0006-fingerprint-and-surface-digest.md

@@ -1,6 +1,7 @@
 # ADR 0006: Fingerprint plus surface digest; cache hints left at the SDK default
 
-**Status:** Accepted (2026-09-04, M0)
+**Status:** Accepted (2026-09-04, M0).
+Its cache-hint clause is superseded by [ADR 0018](0018-the-catalog-carries-a-ttl-and-resource-reads-do-not.md) (2026-09-09); the fingerprint and surface-digest decisions stand.
 
 ## Context
 
@@ -14,9 +15,11 @@ A hand-bumped string cannot prove the surface changed; a digest cannot be read b
 The full-manifest hash is a separate, stronger check pinned only in tests; it moves with the fingerprint but is never reported alone as `surface_digest`.
 The committed snapshot (`tests/fixtures/manifest_snapshot.<profile>.json`) and pinned hash guard both per profile.
 `ttlMs`/`cacheScope` stay at the SDK default (`ttlMs: 0`, `cacheScope: "private"`): fastmcp applies one server-wide hint to every list and read result, and `amicus://models/{backend}` is volatile, so a positive TTL would be wrong for it.
+(Superseded by ADR 0018: fastmcp's hint is still uniform, but the SDK beneath it takes one per method, and the volatility is confined to `resources/read`.)
 The manifest pins the emitted values so a framework change is reviewed, not silent.
 
 ## Consequences
 
 - `surface_digest` and `fingerprint` are excluded from the manifest capture (self-referential), as are release-variable versions.
 - Revisit the TTL when fastmcp offers per-resource hints.
+  Retired rather than met, by ADR 0018: per-METHOD hints proved sufficient.