amicus 0.1.0__tar.gz → 0.3.0__tar.gz

{amicus-0.1.0 → amicus-0.3.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.3.0}/.claude-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
   "name": "amicus",
-  "version": "0.1.0",
+  "version": "0.3.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.3.0}/.codex-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
   "name": "amicus",
-  "version": "0.1.0",
+  "version": "0.3.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.3.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.1.0 → amicus-0.3.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.1.0 → amicus-0.3.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

{amicus-0.1.0 → amicus-0.3.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.2.0",
         "amicus-mcp"
       ],
       "env_vars": [

{amicus-0.1.0 → amicus-0.3.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