feat(mcp): write-capable tools for create_lead, dismiss_lead, apply_record, cv_run, cv_signoff

.rulesync/rules/CLAUDE.md

@@ -198,7 +198,10 @@ print and change nothing until told otherwise, and none offers `--dry-run` — t
 run, and a flag that does nothing is drift. `triage run`/`ingest run`/`track run` invert both halves. The distinguishing
 property is whose judgement the write encodes: a pipeline command acts on a verdict the user
 configured, while a `leads` pass writes over a set the TOOL computed, so a mistyped one should print
-a list rather than change a hundred notes. (`docs/ARCHITECTURE.md` has the per-pass mechanics.)
+a list rather than change a hundred notes. **Exception: `leads dismiss` writes unconditionally on
+every call** (#131), like the pipeline commands, not like its `leads` siblings — the verdict it
+writes is the one the user typed (`--lead`/`--reason`), not one the tool computed. (`docs/ARCHITECTURE.md`
+has the per-pass mechanics.)
 
 **Backends are selected by role, not provider.** `--backend` takes `auto|primary|fallback`
 (`claude-max`/`deepseek` survive as deprecated aliases). Which provider fills each role is config
@@ -312,6 +315,12 @@ application-owned state) and passes that same set as `require_status`, which is
 the invariant when a lead enters the application lifecycle mid-sweep. It is NOT unconditional: a
 lead holding a `pending_cv` sign-off hold (#60) is refused, because dismissing it silently discards
 a composed CV no human has signed off. Any second bulk-dismiss path must refuse the same.
+`Sluice.dismiss_lead()` (#131) is that second writer -- a single-lead dismiss, not a
+bulk sweep, so `expire_report`'s pre-filtering argument does not apply to it; it uses
+its own `_DISMISSABLE_FROM` (the full `TRIAGE_OWNED` set, `dismiss` included) rather
+than `_EXPIRABLE`, and its `pending_cv` sign-off-hold refusal is checked CAS-fresh
+inside the write transform via `require_blank` -- unlike `leads expire`'s equivalent
+refusal, which is still decided from a snapshot.
 
 **Empty config means abstain, not match-nothing.** Every preference gate (`accept_titles`,
 `target_locations`, `reject_companies`, `relevance_keep`/`relevance_drop`, pay floors) defaults to

README.md

@@ -285,23 +285,37 @@ stream each command writes to: [`docs/USAGE.md`](https://github.com/MrReasonable
 | `job-sluice cv` | compose, gate and render a tailored CV, then sign off on it (`run`, `signoff`) |
 | `job-sluice apply` | stage a CV + prep packet, then record a submitted application (`prep`, `record`) |
 | `job-sluice track` | reconcile the funnel from email + calendar signals (`run`, `confirm`, `dismiss`) |
-| `job-sluice leads` | maintenance passes -- report by default, write only when told (`dedupe`, `expire`, `reconcile`) |
+| `job-sluice leads` | maintenance passes -- report by default, write only when told (`dedupe`, `expire`, `reconcile`); `dismiss` writes unconditionally, like a pipeline command |
 | `job-sluice health` | per-source scrape baseline + retire state |
-| `job-sluice mcp` | run a Model Context Protocol server over stdio, for an agent to drive sluice directly (`serve`) |
+| `job-sluice mcp` | run a Model Context Protocol server over stdio, for an agent to drive sluice directly (`serve [--write]`) |
 
 ## MCP server
 
 `job-sluice mcp serve` runs sluice as a Model Context Protocol server over stdio, so
 an agent (Claude Code or otherwise) can call `list_leads`/`get_lead`/`doctor`/`health`
-directly instead of shelling out to the CLI and parsing its stdout. Read-only for
-now -- see [`docs/ARCHITECTURE.md`](https://github.com/MrReasonable/sluice/blob/main/docs/ARCHITECTURE.md)'s surface/adapter section. Needs `pip install -e '.[mcp]'`.
+directly instead of shelling out to the CLI and parsing its stdout. Read-only by
+default -- see [`docs/ARCHITECTURE.md`](https://github.com/MrReasonable/sluice/blob/main/docs/ARCHITECTURE.md)'s surface/adapter section. Needs `pip install -e '.[mcp]'`.
 
-Register it with Claude Code:
+Pass `--write` to also register five write-capable tools -- `dismiss_lead`,
+`apply_record`, `cv_run`, `cv_signoff`, `create_lead` -- each a thin translation
+layer over one `Sluice` write method, never a raw store write. `--write` is a
+per-registration trust decision about one MCP client, not a property of the
+installation: every existing read-only registration is unaffected, and a read-only
+server's `tools/list` genuinely omits the five write tools' names and schemas, not
+merely refusing them at call time.
+
+Register it with Claude Code (read-only):
 
 ```bash
 claude mcp add job-sluice -- job-sluice mcp serve
 ```
 
+...or with write tools enabled:
+
+```bash
+claude mcp add job-sluice -- job-sluice mcp serve --write
+```
+
 ## Rendering prerequisites (`cv.renderer: template` only)
 
 Everything in this section is a prerequisite of ONE renderer -- `template`, the default.

docs/ARCHITECTURE.md

@@ -346,9 +346,14 @@ adapters AND drives the pipeline, so a surface no longer constructs a `Vault()`
 or a `Camofox()`, builds a backend, or duplicates the triage/compose/prep/record/
 track wiring itself. `cli.py` is now a thin shell over `Sluice` -- each command
 builds one, calls one method, and formats the result for the terminal -- so a surface
-built today has nothing left in `cli.py` worth forking. `sluice/mcpserver.py` (#105)
-is the first one: a Model Context Protocol server exposing four read-only tools
-(`list_leads`, `get_lead`, `doctor`, `health`) over stdio.
+built today has nothing left in `cli.py` worth forking. `sluice/mcpserver.py` (#105,
+extended #131) is the first one: a Model Context Protocol server exposing four
+read-only tools (`list_leads`, `get_lead`, `doctor`, `health`) always, and five
+write-capable tools (`dismiss_lead`, `apply_record`, `cv_run`, `cv_signoff`,
+`create_lead`) under `--write`. Every write tool is a thin translation layer over
+exactly one `Sluice` write method -- `sluice/mcpserver.py` itself contains no store
+write (AST-enforced) -- so a write tool can never become a second, undocumented
+write path for an invariant `Sluice`'s own methods already hold.
 
 `tests/conformance/test_store_contract.py` is parameterised over every registered
 store and asserts never-clobber (a re-scrape touches only `last_seen`, and that
@@ -463,6 +468,16 @@ frozen `StalenessPolicy` built by `Sluice.staleness()`. Staleness is a cheap
 proxy: whether a role is still open can only be answered on the employer's own
 site, so it does not replace checking before applying.
 
+**`job-sluice leads dismiss --lead SLUG --reason REASON`** (#131) writes `dismiss`
+by the same route as `leads expire` -- `require_status=_DISMISSABLE_FROM` re-read
+inside the CAS transform, `require_blank={"pending_cv"}` refusing a lead holding
+a #60 sign-off hold -- but is the ONE `leads` pass that writes unconditionally on
+every call rather than reporting by default: the verdict it writes is one the
+USER typed (`--lead`/`--reason`), not one this tool computed, matching the
+pipeline commands' contract rather than `dedupe`/`expire`/`reconcile`'s. Resolves
+by EXACT slug equality, never substring, and refuses (writes nothing) when the
+slug names two or more notes rather than picking one.
+
 **Preventing overwrites of hand-edits** (#109): a sibling guard to
 `require_status`, also on `Vault.update_fields`, named `require_blank`. It
 re-reads the named fields' **current** content inside the CAS transform and

docs/USAGE.md

@@ -159,7 +159,7 @@ exists). Auto-advances status only on a proof-grade, authenticated, non-multi-te
 above the configured confidence floor; every weaker signal becomes a dead-letter proposal that
 resurfaces on every run until a human acts. Prints a summary plus the open-proposal list to
 **stderr** (the whole block, including the digest line):
-```
+```text
 track: msgs=N classified=N auto=N proposed=N calendar_added=N failures=N open=N
   FAILED <message_id>: <cause>
   WARNING: N calendar entries booked from a DTSTART with no usable timezone ...
@@ -210,6 +210,11 @@ exit 0: `track-dismiss: <cleared|would clear> N entr(y|ies)`.
 
 Maintenance passes. **Report by default; none of these offers `--dry-run`, because the
 default *is* the dry run** — a write happens only with the flag named below.
+**Exception: `leads dismiss` writes unconditionally on every call** (#131), like the
+pipeline commands (`ingest run`/`triage run`/`cv run`/`apply record`/`track run`), not
+like its `leads` siblings — the distinguishing property is who decided what to write:
+`dismiss` acts on a verdict the USER typed (`--lead`/`--reason`), while
+`dedupe`/`expire`/`reconcile` write over a set the TOOL computed.
 
 ### `job-sluice leads dedupe [--merge ID ...] [--json]`
 
@@ -235,6 +240,22 @@ outcome is `no-match`/`conflict`/`unreadable`/`skipped`/`ambiguous`. A lead unde
 `pending_cv` sign-off hold is refused rather than dismissed, since that would silently discard
 a composed CV no human has reviewed yet.
 
+### `job-sluice leads dismiss --lead SLUG --reason REASON`
+
+Dismisses ONE lead by EXACT store-issued slug (never a substring match), with
+`--reason` required and appended to `relevance_notes` under a same-day idempotency
+tag -- a same-day repeat is a real `unchanged`, not a duplicate note. Resolves over
+every triage-owned status, `dismiss` included, so re-dismissing an already-dismissed
+lead is a legitimate no-op rather than a regression. Reuses `Sluice.dismiss_lead`
+verbatim -- the same write path the `dismiss_lead` MCP tool calls (see below).
+Refused (writes nothing) if the slug is ambiguous (a name collision), the lead has
+moved into the application lifecycle, or it is held by a #60 sign-off
+(`pending_cv`) -- resolve that first: `job-sluice cv signoff --lead "<slug>"
+--discard`.
+
+Exit 1 for no match, ambiguous, either refusal, or a lost write race (`conflict`);
+exit 0 for `dismissed` or `unchanged`.
+
 ### `job-sluice leads reconcile [--apply] [--json]`
 
 Reports (or with `--apply`, moves) each lead note into the folder its `status` implies — only
@@ -253,16 +274,54 @@ No flags. Per-source scrape baseline and retire state, one line each:
 
 ## `job-sluice mcp`
 
-### `job-sluice mcp serve`
-
-No flags. Runs sluice as a Model Context Protocol server over stdio, so an agent (Claude Code
-or otherwise) can call `list_leads`/`get_lead`/`doctor`/`health` directly instead of shelling
-out to the CLI and parsing its stdout. Read-only for now -- see
-[`docs/ARCHITECTURE.md`](ARCHITECTURE.md)'s surface/adapter section. Needs
-`pip install -e '.[mcp]'`; if the `mcp` package is not installed, exits 2 with a stderr message
-naming `job-sluice[mcp]` as the extra to install (see `sluice/mcpserver.py`'s
-`McpNotInstalled`) rather than a traceback. Blocks for the life of the process once started;
-there is no `--dry-run`.
+### `job-sluice mcp serve [--write]`
+
+Runs sluice as a Model Context Protocol server over stdio, so an agent (Claude Code
+or otherwise) can call sluice's tools directly instead of shelling out to the CLI
+and parsing its stdout. Needs `pip install -e '.[mcp]'`; if the `mcp` package is not
+installed, exits 2 with a stderr message naming `job-sluice[mcp]` as the extra to
+install (see `sluice/mcpserver.py`'s `McpNotInstalled`) rather than a traceback.
+Blocks for the life of the process once started; there is no `--dry-run`.
+
+**Without `--write`** (the default), four read-only tools are registered:
+`list_leads`, `get_lead`, `doctor`, `health`.
+
+**With `--write`**, five more tools are registered:
+
+- `dismiss_lead(lead, reason)` -- dismiss one lead by EXACT slug, recording `reason`.
+- `apply_record(lead, ats=None, url=None)` -- record a sent application (shortlist
+  -> applied).
+- `cv_run(lead, backend="auto")` -- compose and render a CV for one shortlisted
+  lead. The composed text itself is never included in the response.
+- `cv_signoff(lead, discard=False, confirm_token=None)` -- resolve a #60 sign-off
+  hold. `discard=True` clears it outright. **Promoting needs TWO calls**: the first
+  (no `confirm_token`) writes nothing and returns a `confirm_token` bound to the
+  exact claims text; relay the claims to a human, get explicit approval, then call
+  again passing that token back to actually promote. A token whose claims have
+  since changed (a re-compose interleaved) returns `stale_confirmation` with a
+  fresh token, having written nothing.
+- `create_lead(title, company, url, location="", salary="", job_type="",
+  source="manual")` -- create a new lead note directly, for a job a human found
+  that no scanner ingested. Lands at `status: new`; `job-sluice triage run`
+  promotes it from there. Reports `upsert`'s own outcome vocabulary verbatim:
+  identity is company+title, and a second call at that same identity bumps
+  `last_seen` ONLY, reported as `updated` when the incoming url (or, absent a
+  url match, the location) proves the same posting, or `merged` when neither
+  does (inconclusive evidence -- e.g. a blank-url lead whose location is
+  blank, or is compared against a note whose own location is blank) -- UNLESS
+  the two locations are proven DIFFERENT (two non-blank, non-overlapping
+  locations), in which case the call creates a genuinely NEW note instead
+  (`created` again -- a second real note at the same company+title). Both
+  `updated` and `merged` are a bare `last_seen` bump; the new
+  url/salary/location is NOT recorded either way. `slug` is OMITTED from the
+  response only for `refused`/`merged_away`/`merged_away_unproven`, which
+  write nothing and so never have a slug to report -- `created`/`updated`/
+  `merged` always carry the slug of the note this call actually touched, the
+  store's own answer, never a guess.
+
+`--write` is a per-registration trust decision about one MCP client: every existing
+read-only registration is unaffected, and a read-only server's `tools/list`
+genuinely omits the five write tools, not merely refusing them at call time.
 
 ## `job-sluice init`