leyline-code 0.8.1__py3-none-any.whl

leyline/skills/leyline-adversarial-review/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: leyline-adversarial-review
+description: Attack a change as a logic reviewer or a performance reviewer, using a Leyline map as evidence. Use on a spec after its brief exists and before any code is written, or on a pull request or branch someone else wrote (no spec needed), or when asked to review, challenge or stress-test a change.
+---
+
+# Review a change adversarially with Leyline
+
+Two kinds of change can be reviewed: a **spec** (an OpenSpec folder, before any code is written) and a **pull
+request** (code someone already wrote, with no spec; see the section below). Your job is to find what is
+wrong with a change before it costs anything. You are not the author
+and you are not trying to help it pass. Run as a fresh agent that has not seen the spec being
+written. If you cannot start one, do the review as a separate pass: put aside what you know of how
+the spec was written, re-read only the change folder and `leyline.md`, and say in your report that
+the review was not done by a fresh agent. Do one review per run: logic or performance.
+
+It works with the Leyline MCP server or with the `leyline` command alone. Without the server:
+`spec_review_facts` is `leyline spec facts <id> --reviewer logic` (or `performance`), which prints
+the same facts as JSON and records that the review ran; `spec_finding` is `leyline spec finding <id>
+--reviewer logic --severity medium --claim "..." --evidence <node id> ... --proposal "..."`;
+`source`, `expand`, `search` and `impact` are `leyline source <id>`, `leyline expand <id>`,
+`leyline search <text>` and `leyline impact <name>`. If neither is there, say so and stop.
+
+## Steps
+
+1. Read the change folder: `proposal.md`, the spec deltas, `tasks.md`, `leyline.md`. For a pull request,
+   read its page (`.leyline/reviews/pr-<id>.md`) and the diff.
+2. Call `spec_review_facts` with the folder and `reviewer` (logic or performance). It returns what
+   the graph knows, arranged as the questions below, and records that your review ran, so a review
+   that files nothing still shows on the plan.
+   - Read `learnings_that_apply` first: past findings on this code that a person rejected, with their reason.
+     A finding you file that repeats one comes back with `learned`; it is kept and marked on the page.
+     A learning marked `stale` is about code that has changed since the decision (`edited` and `gone` name
+     the nodes). It is a question for the person, not an answer: read the new code, and file what you find
+     as usual. Do not drop a finding because a stale learning matches it, and do not refile one to get
+     around it. Say in your report which stale learnings you met, so the person can confirm or retire them.
+     A learning whose `code` is unknown was kept before Leyline recorded its code: treat it as current.
+3. For every item in your section, read the code (`source`, `expand`, `flow`, or the file itself)
+   before deciding. A fact from the graph is a lead, not a finding.
+4. File each real problem with `spec_finding`: one sentence a person can check, a severity, the node
+   ids that show it, and the change to the spec you propose. No node, no finding.
+5. Report the count by severity and the one finding you would fix first. Stop there.
+
+## A pull request: set it up first
+
+When the person asked for the whole review of a pull request, follow the leyline-pr-review skill: it runs this
+one twice and writes the summary. Alone, this skill is the attack step.
+
+1. Check the branch out (`gh pr checkout <number>`), then call `review_pr` with `base` (the branch it merges
+   into) and `about` (its title and description, and each linked issue's title and body), or `github` with the
+   number; without the server, `leyline pr <base> --about "..."` or `leyline pr --github <number>`. It returns the review's id,
+   `pr-<id>`, and a page: what changed, what it reaches and did not change, its tests.
+2. Use `pr-<id>` wherever the steps below say the change folder: `spec_review_facts` with it gives the facts
+   (`leyline spec facts pr-<id> --reviewer logic`), and `spec_finding` files against it. Read the files under
+   `house_rules_to_read_first` before anything else: a pull request breaks the repository's own rules more
+   often than it breaks the code.
+3. In the questions below, read "the spec" as "the description". The first logic question for a pull request
+   is whether the code does what the description says, all of it and nothing else: name each edit the
+   description does not explain, and each thing it promises that no edit does. `proposal` in a finding is the
+   change to the code (or the description) you propose.
+4. The facts for a pull request use the same questions under names without "task": `other_ends_of_those_channels_not_edited`,
+   `callers_of_changed_functions_left_alone`, `state_shared_with_unchanged_code`; and add
+   `signature_changed_callers_not_edited`, `removed_but_still_called` and `tests.likely_to_fail_unedited`.
+5. A finding whose evidence is not on the change's blast radius comes back with a warning. Either add the node
+   that links it to the change, or ask yourself whether you wandered.
+6. On a re-review (new commits since the last one; the facts' `since_last_review` names the previous head), start
+   from `since_last_review`: read the code changed since then and its `new_facts` first, re-check each finding under
+   `may_be_fixed` and tell the person which ones the new code fixed, and do not refile findings under `still_applies`.
+
+## Logic reviewer: answer each of these
+
+- Which callers, implementers or overriders must change and have no task? (A pull request:
+  `signature_changed_callers_not_edited` and `removed_but_still_called`. Each is a likely break; confirm it
+  in the code.)
+- Which channel does the change cross (process, HTTP, file, event), and does the spec say what the
+  other end must do? `other_ends_of_those_channels_no_task_names` lists the other launchers, callers or
+  readers of the same end: does each one need the change too?
+- Which shared field gains a writer, or changes meaning for its existing readers?
+- Which new member is named like one its type already has (`new_members_named_like_existing_ones`)?
+  Read every user of the existing one: does it need the new one too?
+- Who else calls each changed function (`callers_of_changed_functions_the_spec_leaves_alone`)? Does
+  the change alter what those callers get or can assume?
+- Which state do the changed functions use that other, unchanged functions also use?
+- For each scenario: would its test still pass if the task it is meant to prove were left out?
+- Which scenario has no test? Which requirement has no scenario?
+- What do the scenarios leave out: the error path, the empty case, ordering, the second caller,
+  what happens to data written before the change?
+- Which existing rule or pattern does the design break, and is that said?
+- Does any task contradict another, or the proposal?
+
+## Performance reviewer: answer each of these
+
+- Which changed functions do the most flows pass through, and which sit inside the main loop? Read
+  the callers to confirm: the count of flows is a proxy.
+- Does the change add work per call, per item or per tick on those functions?
+- Does it add allocation, I/O, serialisation, a lock or a process hop on a hot path?
+- Does it grow a message or a structure that crosses a channel on every step?
+- What is the measured baseline, and which test would show a regression? If none exists, that is a
+  finding.
+
+## Severity
+
+- **high**: the change will be wrong, or will break something the spec does not mention, if
+  implemented as written.
+- **medium**: a gap that will probably cost a second round.
+- **low**: worth a sentence in the spec.
+
+## Rules
+
+- Do not rewrite the spec, or push to someone else's branch. Propose the change in the finding and let the
+  person decide.
+- Do not file style or naming preferences.
+- Do not refile what a learning already settled, unless the code changed in a way its reason did not cover.
+  Then say in the claim what changed.
+- A finding whose claim starts "/opsx:verify:" was filed from OpenSpec's verify (the leyline-spec skill says how).
+  It is an LLM's opinion: read the code behind it like any other lead, and do not file it again. It does not
+  change `check`'s verdict, and `check` passing does not settle it.
+- A stale learning settles nothing on its own. Keep the finding it matches; the page shows the person that
+  the code changed, and they decide (`learnings` with `confirm` or `retire`, only on their word).
+- If the facts are empty and you found nothing after reading the code, say so in one line. A review
+  that finds nothing is a valid result.
+- Say what you could not check and why.

leyline/skills/leyline-ask/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: leyline-ask
+description: Answer a question about a mapped codebase from its Leyline map and its source, citing the code. Use when asked how something works, what happens when something runs, what a part of the code holds, where something is, who calls it, or what changing it would affect.
+---
+
+# Answer a question about the code with Leyline
+
+Answer from the map and the source, never from memory. Every claim names the code it rests on.
+
+It works with the Leyline MCP server or with the `leyline` command alone:
+
+| MCP tool | Command |
+| --- | --- |
+| `map` | `leyline map <repo>` |
+| `overview`, `search`, `expand`, `source` | `leyline overview`, `leyline search <text>`, `leyline expand <id>`, `leyline source <id>` |
+| `neighbors` | `leyline neighbors <id> --direction in --kinds calls` |
+| `impact` | `leyline impact <name or id>` |
+| `context` | `leyline context <name, path or id> --tokens 2000` |
+| `module_outline` | `leyline outline [module]` |
+| `trace`, `flows`, `flow` | none; use the server |
+
+If neither is there, say so and stop. If a tool says nothing is mapped, call `map` first.
+
+## Route the question
+
+| The question | Do this |
+| --- | --- |
+| How does X work? What happens when Y? | the leyline-explain-flow skill |
+| What is in this part? Where do I start? | the leyline-explore-module skill |
+| What would changing X affect? | the leyline-change-impact skill (`impact` alone for a quick answer) |
+| Who calls X? Where is X? What does X use? | the steps below |
+
+## Steps
+
+1. **Find the code.** `search` with one distinctive word of the name, then `expand` the best hit to confirm it.
+   If two things fit, say which you picked and why, or ask.
+2. **Use the narrowest tool.** Who calls it: `neighbors` (direction in, kinds calls). Everything that can reach
+   it: `impact`. What it calls and the fields it touches: `expand`. The code around it: `context`. How one
+   function reaches another: `trace`.
+3. **Read before you claim.** Call `source` on each thing you will say something about. The map says that A
+   calls B, not why or under what condition.
+4. **Answer** in a few sentences, then the evidence.
+
+## Say how sure you are
+
+- Cite each claim with its node id, or `path:line`.
+- Say which links are exact (a compiler confirmed them), which come from syntax, and which are guesses
+  (marked `guess` or `guessed`). A guessed link is a lead to check in the source, not a fact.
+- Say what the map cannot see: calls by reflection or a name built at run time, a channel whose other end is
+  built at run time, files in a language with no adapter, extractors that did not run (`overview` lists them).
+- Say what you did not read.
+
+## Rules
+
+- No node, no claim. Never guess a node id: take it from `search`, `overview` or `expand`.
+- Answer what was asked. Offer the next question; do not answer it unasked.
+- Do not edit code or write views while answering a question.

leyline/skills/leyline-change-impact/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: leyline-change-impact
+description: Assess a described code change against a Leyline map and save a blast-radius view, review an implemented change against its proposal, or save any custom view of the code. Use when asked what a change will touch, break or need tested, or whether a change went as planned.
+---
+
+# Assess a change with Leyline
+
+Use this when the user describes a change (a spec, a ticket, a sentence) and wants to know what it
+touches before any code is written, or asks for a picture of some slice of the codebase. It needs the
+Leyline MCP server connected and the repository indexed. If the `overview` tool is missing, say so and
+stop: do not guess the impact from memory.
+
+A question about the code with no change in mind goes to the leyline-ask skill. A change to plan and check with a
+spec is the leyline-spec skill; a one-line fix, leyline-quick-change.
+
+Leyline computes reach; you decide which nodes the words refer to. Keep those two jobs separate and
+tell the user which is which.
+
+## Steps
+
+1. **Read the change.** Restate it in one sentence. If it could mean two different things in this
+   codebase, ask before going on.
+2. **Orient.** Call `overview` once. Note the modules, the systems and which extractors did not run:
+   anything marked not analyzed is a blind spot for this assessment.
+3. **Find the targets.** For each thing the change mentions, use `search`, then `expand` to confirm
+   it is the right node. Read `source` when the name alone does not settle it. Prefer functions over
+   whole types: a type target counts every function inside it and inflates the result.
+4. **Choose an action for each target.**
+   - `behavior`: same parameters and return type, different result or side effect
+   - `signature`: parameters or return type change
+   - `rename`, `remove`
+   - `add`: something new. Give its `name`, the `parent` it goes in, what it `uses` and what is `used_by` it.
+5. **Look across channels yourself.** If a target sends or receives data over a process pipe, an
+   event, a file or the network, the code on the other side has no link to it in the graph. Find the
+   reader or writer on the far side (`search`, `source`) and add it as a target with a note that says
+   what it must do. Leyline flags that a channel is involved; it cannot tell you which function
+   parses the bytes.
+6. **Call `propose_change`** with the user's intent in their words, a short title and the targets.
+   Give every target a `note` saying what changes there.
+7. **Read the result before reporting.** Check that `must_edit` makes sense. If it is empty for a
+   breaking change, or huge for a small one, a target is probably wrong: fix it and call again.
+   Follow up with `impact` or `flow` on anything surprising.
+8. **Report** in this order: what must be edited, the risks as flagged, the tests to run, what no
+   test covers, and what Leyline could not see. Tell the user the view is saved under the title you
+   gave it and appears in the map's Views tab after a refresh.
+
+## After the change is implemented
+
+Do this when the user asks whether a change went as planned, or when you implemented it yourself.
+
+1. Before editing, run the tests and call `record_test_run` with run `before`. If the edits are
+   already made, skip this and say the review has no test baseline.
+2. After the edits, run the tests again and record run `after`. Ask for the repository to be
+   re-indexed (`leyline index`); the review compares stores, not files.
+3. Call `review_change` with the change id and the two run labels.
+4. Report the findings first. Then, for each edit that was not predicted, read its `source` and say
+   whether it was a needed follow-on the proposal missed or drift outside the change. For each
+   predicted edit that did not happen, say whether the prediction was wrong or the work is unfinished.
+5. A new link between modules or a newly broken rule is a design decision: put it to the user, do
+   not wave it through.
+
+To record a design constraint, call `add_rule`. Pass `confirmed=true` only when the user stated the
+rule themselves; a rule you inferred from the code or the docs is a suggestion, with your `reason`.
+
+## Custom views
+
+When the user wants to see something that is not a change (how a feature works end to end, two
+design options side by side, everything that touches one concept), collect the node ids and call
+`save_view`. Group marks with short `role` labels, give each a one-line `note`, describe the roles in
+`legend`, and explain the view in `narrative`. To compare design options, save one view per option
+with the same role names so they read alike.
+
+## Rules
+
+- Never present the reach as proof the change is safe. It is static: it shows what can be affected,
+  not whether behavior stays correct.
+- Say when a link in the result is marked guessed.
+- Do not write annotations or views about code you did not look at.
+- After the change is implemented, ask for the repository to be re-indexed before assessing again.

leyline/skills/leyline-explain-flow/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: leyline-explain-flow
+description: Answer "how does X work" or "what happens when Y" about a mapped codebase by finding where the behavior starts and walking it step by step on a Leyline map, reading the code at each step. Use when asked to find, trace, follow or explain a flow, a request, a feature or a code path from a description, especially in a large repository.
+---
+
+# Explain a flow with Leyline
+
+The person describes a behavior in words. Leyline finds where it could start and walks the calls and channels from
+there; you decide which start fits, read the code, and write the answer. Leyline holds no language model: every step
+it gives is a link on the map, and every sentence you write must rest on one of those steps or on code you read.
+
+It works with the Leyline MCP server or with the `leyline` command alone:
+
+| MCP tool | Command |
+| --- | --- |
+| `find_flows(description)` | `leyline find-flows "<description>"` |
+| `explain_path(start, to?, through?, max_steps?)` | `leyline explain-path <start> [--to X] [--through Y] [--steps N]` |
+| `diagram(ids)` | `leyline diagram <id or name> ...` |
+| `source(node_id)` | `leyline source <id>` |
+| `save_tour(title, stops)` | none: the server only |
+| `map` | `leyline map <repo>` |
+
+Add `--json` to a command for the same fields the tool returns. If neither the server nor the command is there, say so
+and stop. If a tool says nothing is mapped, run `map` first.
+
+## Steps
+
+1. **Restate the question** in one sentence, in the code's terms if you know them ("what happens when a writer saves
+   a dialogue: from the editor's Save to the file on disk").
+2. **Call `find_flows`** with the question in plain words. Each candidate has its kind (route handler, UI event
+   handler, program entry, message handler, test, function), `at` (file:line), `why` it matched, and the flows that
+   start there (`flows`); where none starts, the entry points' flows that reach it (`reached_from`) and the tests'
+   (`tests_reaching`).
+3. **Pick the start.** When `ambiguous` is true, or the first few candidates are different things (a UI handler, a
+   route, a test), show the person two to four of them, one line each, and ask which they mean; or pick one and say
+   why in a sentence. A UI or command handler is usually the best start for "what happens when"; a route handler when
+   the question is about the server; a test whose name states the behavior when nothing else fits. If no candidate
+   fits, call `find_flows` again with the words the code would use, or use `search`.
+4. **Call `explain_path`** from that start. With nothing else it follows the main flow; give `to` when the question
+   names an end ("until it is written to disk") and `through` when it names a stop on the way. Raise `max_steps`, or
+   walk again from a later step, when `left_out` hides the part that matters.
+5. **Read the code** (`source`) at every step you will say something about: the start, each step that crosses a
+   channel (`crosses`), each `later_elsewhere`, and each step whose name does not say what it does. The excerpt in a
+   step (`call`, `declaration`) is one line; it is not enough to say what a function does.
+6. **Write the answer** as a short numbered walk, one step a line, each naming the code and where it is:
+
+   > 1. The Save button's handler `DialogueCanvas.save` (DialogueCanvas.tsx:230) calls `saveEntity` in the store.
+   > 2. `performSave` (store.ts:867) sends `PUT /api/entities/:type/:id` to the host, a separate process.
+   > 3. The host's handler for that route (server.ts:361) checks the entity's shape, then `saveOne` writes the file.
+   > 4. It then calls `scheduleValidation` (validation.ts:161); validation runs later, off the request.
+
+   Say where the walk crosses into another process, program or service, and where data is written for something
+   that reads it later. Skip steps that add nothing (a helper that formats a string); keep the ones a person would
+   need to change the behavior.
+7. **Include the diagram**: the `mermaid` text of the walk, in a ```` ```mermaid ```` block. Use `diagram` for a
+   different set of functions.
+8. **Say what the map could not see**: the `not_seen` notes that apply (calls through callbacks or frameworks, an
+   interface whose implementation is picked at run time, links guessed by name, messages sent over a program's pipes,
+   a walk cut at its depth limit), in one or two sentences.
+9. **Offer to save it as a tour** so it can be reopened from the map page. If the person agrees, call `save_tour`
+   with one stop per step you wrote, each `{"title", "kind": "node", "ref": <step id>, "narrative": <your sentence>}`.
+
+## Rules
+
+- Every claim cites a node: its name and file:line, from a step or from code you read.
+- Never invent a step the map or the code does not show. If the walk stops where the behavior clearly goes on, say
+  where it stops and why (`not_seen`), and read the code to find the next step yourself; say that you found it by
+  reading, not on the map.
+- A step marked `guessed` is a link the map found by name: check it in the code before relying on it.
+- Keep the answer short: a walk of 4 to 10 steps, the diagram, and the blind spots. Offer more depth, do not pad.

leyline/skills/leyline-explore-module/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: leyline-explore-module
+description: Explore one large module of a mapped codebase with Leyline, name its parts from their code, and give the person a one-screen guide to it. Use when asked what a module or folder holds, where to start reading in it, how its parts connect, or which parts are risky to change.
+---
+
+# Explore a large module with Leyline
+
+On a large repository one module can hold hundreds of files. Leyline splits it into at most twelve parts
+(folders, or groups of files that work together where a folder is flat). You read each part, name it, and
+give the person a guide they can read in one screen.
+
+It works with the Leyline MCP server or with the `leyline` command alone:
+
+| MCP tool | Command |
+| --- | --- |
+| `module_outline` | `leyline outline [module or part id] --depth 2` (`--json` for the ids) |
+| `name_part` | `leyline name-part <part id> "<name>" --summary "<one line>" --evidence <node ids>` |
+| `source`, `context` | `leyline source <id>`, `leyline context <name or path> --tokens 2000` |
+| `search`, `expand` | `leyline search <text>`, `leyline expand <id>` |
+| `save_tour` | none; use the server |
+
+If neither is there, say so and stop. If a tool says nothing is mapped, call `map` first.
+
+## Steps
+
+1. **Pick the module.** Take the one the person names. If they name none, call `module_outline` with no
+   module and take the largest. A part id from an earlier outline works too.
+2. **Get the outline.** `module_outline(module)`. It gives each part's size, entry points, what it uses and
+   what uses it, channels, busiest functions, key types and risks. Note the parts that already have a name:
+   do not rename one the person named (`named_by`), and read again any marked `stale`.
+3. **Read each part.** For each part without a name, read the code that tells you what it is for: its
+   busiest functions and key types (`source` on their ids), its entry points, and for a folder its main
+   file. `context` on a part's key function shows the code around it. Read at least two items per part.
+4. **Name each part.** `name_part(part_id, name, summary, evidence)`: a short name a person would use
+   ("Validation rules", not "validation folder"), a one-line summary of what it does, and as evidence the
+   node ids you read. Skip a `@more` part: it only holds the rest of the level.
+5. **Go one level down where it helps.** A part with many files and no clear purpose: call
+   `module_outline` with its id, and repeat steps 3 and 4 for its parts. Stop at two levels unless asked.
+6. **Write the guide.** Call `module_outline(module)` again so the names show, then give the person one
+   screen:
+   - one line on what the module does;
+   - the parts, each with its name and summary, largest first;
+   - how they connect: which parts call which, and the channels to other modules (routes, files, events);
+   - where to start reading for two or three common tasks, each a part and a function or type in it;
+   - which parts are risky to change: busy (on the most flows), many dependents, or few tests (from
+     `risky`), and why.
+7. **Offer to save it as a tour** (the leyline-tour skill, `save_tour`), one stop per part, in reading order.
+
+## Rules
+
+- Names come from reading code, never from folder names alone. Cite the nodes you read for each part.
+- One screen per level. Put detail behind a drill-down, not in the guide.
+- Say what the outline cannot see: a part reached only through a framework, a callback or a channel the map
+  did not follow can look unused.
+- Do not edit code while exploring.

leyline/skills/leyline-pr-review/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: leyline-pr-review
+description: Review a pull request or branch someone else wrote, with no spec, using a Leyline map. Maps what changed and what it reaches, runs an adversarial logic and performance review, and gives the person a short summary with the one finding to fix first. Use when asked to review a pull request, a branch or someone's changes, or to review one again after new commits.
+---
+
+# Review a pull request with Leyline
+
+The code exists; what it was meant to do is a title and a paragraph. Leyline reads the change from the code.
+Your job is to tell the person what it does, what it breaks or leaves undone, and what to fix first.
+
+It works with the Leyline MCP server or with the `leyline` command alone:
+
+| MCP tool | Command |
+| --- | --- |
+| `review_pr` (`base`, `about`) | `leyline pr <base> --about "<title and description>"` |
+| `review_pr` (`github`) | `leyline pr --github <number>` |
+| `review_pr` (`gate_passed`, `blocking`) | `leyline pr <base> --gate` (exits 1 while something blocks) |
+| `spec_review_facts` | `leyline spec facts pr-<id> --reviewer logic` (or `performance`) |
+| `spec_finding` | `leyline spec finding pr-<id> --reviewer logic --severity high --claim "..." --evidence <node id> --proposal "..."` |
+| `spec_findings` | `leyline spec findings pr-<id>` |
+| `affected_tests` | `leyline affected-tests pr-<id>` |
+| `source`, `expand`, `impact` | `leyline source <id>`, `leyline expand <id>`, `leyline impact <name>` |
+
+If neither is there, say so and stop.
+
+## Steps
+
+1. **Check the branch out** (`gh pr checkout <number>`, or `git switch <branch>`). Leyline reads the working
+   tree, so review the checkout, not a diff pasted in.
+2. **Read what it was meant to do.** `gh pr view <number> --json title,body,closingIssuesReferences`, then
+   `gh issue view <m> --json title,body` for each linked issue. If `gh` is not there or no issue is linked, say so
+   and go on with the title and description alone.
+3. **Call `review_pr`** with `base` (the branch it merges into) and `about`: the title and description, then each
+   linked issue's title and body (`--about-file` for long text). With `github`, still pass `about` when there are
+   linked issues. Keep the `change_id` (`pr-<id>`). Read the page, and the files under
+   `house_rules` before anything else: a pull request breaks the repository's own rules more often than the code.
+4. **Run the leyline-adversarial-review skill** on `pr-<id>` twice: once as the logic reviewer, once as the
+   performance reviewer. Fresh agents are best; if you cannot start one, do two separate passes and say so.
+   Each files its findings with `spec_finding`.
+5. **Hold the code against each linked issue.** Decide from the page's "What changed" and the code, not from the
+   description, whether it addresses the issue. Where the code and an issue disagree, file a logic finding with
+   `spec_finding`, the issue's number in the claim.
+6. **Call `spec_findings`** with `pr-<id>`: everything filed, with ids.
+7. **Call `review_pr` again** so the gate counts the findings just filed. It returns `gate_passed` and
+   `blocking`: what holds up the merge under the project's `[pr] blocking` in `openspec/leyline.toml` (by
+   default unedited callers of a changed signature, removed code still called, confirmed error rules newly
+   failing, and open high findings).
+8. **Summarize for the person**, in this order, on one screen:
+   - **Gate**: passes, or blocked, with each line of `blocking` and what to do about the first (the page's
+     `Next:` line). Say which config it ran under (the default, or `openspec/leyline.toml`).
+   - **What changed**: two sentences, from the page's "What changed", not from the description.
+   - **Linked issues**: one line each: addressed, partly or not, citing "What changed". Or say there were none, or
+     that `gh` was not there.
+   - **What it breaks or leaves**: callers of a changed signature left alone, removed code still called, other
+     ends of a channel not edited, changed code no test runs. One line each, with the node.
+   - **Findings**: high, then medium, then low; one line each, with its id and its evidence.
+   - **Fix first**: the one finding to fix first, and why.
+   - **Not checked**: what you could not check, and why.
+9. Point to the page (`written`) for the whole review. Ask the person to decide each finding; record a decision
+   they state with `spec_resolve`.
+
+## Review it again after new commits
+
+Check the new commits out and call `review_pr` again, with the same `review_id` or `github` number. The page
+opens with "Since the last review", and the facts carry `since_last_review`:
+
+1. Start there: the functions edited since the last head, and its `new_facts`.
+2. Re-check each finding under `may_be_fixed` in the new code, and tell the person which the new commits fix.
+3. Do not file again what is under `still_applies`.
+4. Review only the new code adversarially. Open the summary with what changed since the last review, and
+   whether the gate result changed: it is judged again from the new code and the findings as they stand.
+
+## Rules
+
+- Do not push to the author's branch or edit their code. Propose; the person decides.
+- Do not resolve a finding on your own judgment.
+- Describe the change from the code. Where the description, or a linked issue, and the code disagree, that is a finding.

leyline/skills/leyline-quick-change/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: leyline-quick-change
+description: Make a small code change (a constant, one function and its caller) on a mapped codebase with no spec folder, and have Leyline say whether it was done. Use when asked for a one-line fix, a changed value or a small tweak, and to decide when a change has grown and needs a spec.
+---
+
+# Make a quick change with Leyline
+
+`quick` gives a small change the same answers as a spec, with no folder: what it will touch, what it reaches,
+and whether it was done. Three steps: `quick` before, the edit, `quick` with `done` after.
+
+It works with the Leyline MCP server or with the `leyline` command alone:
+
+| MCP tool | Command |
+| --- | --- |
+| `quick` (`what`, `names`, `test_output`) | `<test command> \| leyline quick "<what>" --about <names> --tests -` |
+| `quick` (`done`, `test_output`) | `<test command> \| leyline quick --done quick-<slug> --tests -` |
+| `quick` (`done`, `names`) | `leyline quick --done quick-<slug> --about <name>` |
+| `search`, `expand`, `source` | `leyline search <text>`, `leyline expand <id>`, `leyline source <id>` |
+| `affected_tests` | `leyline affected-tests quick-<slug>` |
+| none | `leyline quick --to-spec <id> quick-<slug>` |
+
+If neither is there, say so and stop.
+
+## Is it quick?
+
+Quick fits a value or one or two functions, with no design to agree. Use the leyline-spec skill instead when:
+
+- the person has to choose between designs, or agree what "done" means;
+- it adds a feature, a public API or a data format;
+- it changes what crosses a channel (a route, an event, a queue, a table, a file, a program's input): both ends
+  must agree.
+
+## Steps
+
+1. **Find the code.** `search`, then `expand` to confirm. Use names as the code writes them: `Owner.method`,
+   `module.func`, a constant.
+2. **Before the edit.** Run the tests. Call `quick` with `what` (one sentence), `names` and `test_output`. If
+   you cannot run the tests, say so: without them `done` cannot tell a test the change broke from one that
+   already failed.
+3. **Read the answer:** what it will touch, what must be edited with it, the channels, the tests that run it.
+   Tell the person anything bigger than they said. If `grown` is not empty, stop and escalate (below).
+4. **Edit** the named code, and what the answer says must be edited with it. Nothing else.
+5. **After the edit.** Run the tests (`affected_tests` names the ones to run), then call `quick` with `done` (the
+   `change_id`) and `test_output`.
+6. **Report the verdict as it comes:** `done`, then each item with its verdict and why. An edit that belonged
+   but was not named: call `quick` again with `done` and `names` to add it. Do not leave it out of the report.
+7. If `grown` is not empty now, escalate.
+
+## Escalate to a spec
+
+`grown` says why: too many pieces of code, callers that must change, or a channel crossed. Then:
+
+1. Tell the person why the change grew, in a sentence.
+2. Write `openspec/changes/<id>/` with the leyline-spec skill.
+3. Run `leyline quick --to-spec <id> quick-<slug>`: the spec starts from this baseline and the tests from before.
+4. Go on with `plan` and `check`, as leyline-spec says.
+
+## Rules
+
+- Never call the change done from your own account. `quick` with `done` reads the code.
+- Do not widen the edit to tidy nearby code. That is a second change.
+- For a review, use the change id as a spec's: `spec_review_facts` with `quick-<slug>`. The person resolves
+  findings, not you.