---
name: semctx-semantic
description: >-
  Carry intent, invariants, decisions, evidence and unknowns through a non-trivial change using the
  semctx semantic layer. Use when starting substantial work: open or select a change contract, pull a
  bounded semantic slice, then keep the contract honest as you edit — verify impact, compose the
  change verdict, run the recommended tests, and record proofs/unknowns. Never conclude on a BLOCK.
---

# Working a change with the semctx semantic layer

This is the focused Plane B workflow. Use `semctx-control` when the task also needs repository
impact, L0-L6 tracing, migration planning, or the shared Codex/Claude completion contract.

The semantic layer is **authored truth** (Plane B) that sits beside the deterministic repository
graph (Plane A). It answers *"which intention, invariants, decisions, evidence and unknowns must
survive while I change this system?"* — it does **not** find files for a task (that is grep/BM25/
embeddings; see ADR 0005). Everything is deterministic and works with no LLM; you make it better.

Pass the absolute project root as `repositoryRoot` on every MCP call. The server rejects missing or
relative roots so a plugin-cache working directory can never become the implicit target.

## The loop (non-trivial change)

1. **Check semantic integrity.** Call `semctx_semantic_check` and preserve every canonical reason
   code. Do not continue into a write loop with an invalid/mismatched pointer, obsolete active
   contract, or stale verification baseline.

2. **Open or select a change contract.**
   - `semctx_change_open` with `{ id: "change.<slug>", statement, preserves: [...], serves: [...],
     requires: [...], unknowns: [...] }`. It becomes the active change (provenance `agent`).
   - `preserves` are the invariants this change must not break; `requires` are the proofs you will
     owe; `unknowns` are the open questions you must not silently drop.

3. **Pull a bounded semantic slice.** `semctx_semantic_slice { changeId }` (or `symbolRef` /
   `claimRef`). Read the capsule: Intentions, Invariants, Decisions, Linked symbols/claims, Evidence
   obtained, Open unknowns, **Forbidden / safety constraints**, Next expected proofs. It is bounded
   and every line points to a source — treat anything absent as **unknown**, not as false.

4. **Edit the code.**

5. **Analyse impact.** Call `semctx_verify_change` (Plane A: impacted symbols/contracts/invariants,
   recommended tests, PASS/WARN/BLOCK). This is unchanged and still first-class.

6. **Compose the change verdict.** Call `semctx_change_verify { changeId }`. It reuses the impact
   report verbatim and folds in the contract:
   - **VERIFIED** — all preserved invariants proved/untouched, all required evidence proved, no open
     blocking unknown, no stale link.
   - **PARTIAL** — open non-critical unknowns or unproven required evidence; nothing blocking.
   - **BLOCKED** — an underlying BLOCK, a critical preserved invariant touched without a test, a
     contradicted invariant, or (per config) a superseded decision in use.
   - **STALE** — a repository link no longer resolves (the model drifted from the code) — re-link
     before trusting the verdict.

7. **Run the recommended tests** from the impact report. They must pass.

8. **Record progress.** When you actually obtain a proof (you ran the test and it passed), update the
   evidence node's status to `tested` / `runtime_verified`. Before resolving an unknown, ensure its
   authored node declares `proved_by` to that proven evidence; then use
   `semctx_change_update { id, resolveUnknowns: [...] }`.

9. **Close through proof.** `semctx_change_close { id }` reruns composed verification and derives
   `verified` only from a VERIFIED result. Generic updates cannot assert that lifecycle.

## Rules

- **Never conclude "done" on a BLOCKED verdict.** Resolve the finding (add the test / fix the change)
  or the user explicitly disables the rule in `.semctx/config.json`.
- **On PARTIAL, say exactly what remains unproven** — list the pending evidence and open unknowns.
  PARTIAL is honest, not finished.
- **On STALE, re-link before trusting anything** — a stale link means the declared coupling drifted.
- **Never invent a relation, a proof or an invariant.** Only cite what the slice / reports show. If
  the model does not declare it, it is an open unknown.
- **Keep the two planes distinct.** A structural fact ("X calls Y") is Plane A; an intention ("X must
  never happen twice") is Plane B. Do not launder one into the other.

## Handoff before compaction

Before a context compaction or handing the work to a fresh agent, call `semctx_handoff` (optionally
with a `note`). It captures the active change, touched invariants, obtained/pending proofs, open
unknowns and next validations into `.semctx/working/`. On resume, call `semctx_resume` to rehydrate a
short, stable capsule. These are explicit tools — do not rely on any implicit compaction hook.

## Local equivalents (no MCP)

Prefer the plugin-bundled CLI (`dist/semctx.js`, same release as MCP). Claude Code substitutes the
plugin root into this skill at load time, so the path below is already absolute; if it still reads
as a literal `${…}` placeholder, use a global `semctx` on PATH instead (same version: `semctx
--version`), or report that no shell CLI is available. `CLAUDE_PLUGIN_ROOT` is never exported to
your terminal — do not rely on the shell to expand it.

```
bun "${CLAUDE_PLUGIN_ROOT}/dist/semctx.js" semantic init                         # scaffold .semctx/semantic/ (versioned)
bun "${CLAUDE_PLUGIN_ROOT}/dist/semctx.js" semantic check --json                 # integrity + lifecycle reason codes
bun "${CLAUDE_PLUGIN_ROOT}/dist/semctx.js" change open change.<slug> --preserves <inv-ids> --unknown <unknown-ids>
bun "${CLAUDE_PLUGIN_ROOT}/dist/semctx.js" semantic slice --change change.<slug> --format agent
bun "${CLAUDE_PLUGIN_ROOT}/dist/semctx.js" verify diff --base origin/main         # Plane A impact
bun "${CLAUDE_PLUGIN_ROOT}/dist/semctx.js" change verify change.<slug> --base origin/main   # composed verdict
bun "${CLAUDE_PLUGIN_ROOT}/dist/semctx.js" semantic handoff                       # / semctx semantic resume

semctx semantic check --json                                                     # global fallback
```