agent-bios 0.9.8 → 0.10.0

package/claude/guides/concept-economy.md

@@ -0,0 +1,187 @@
+---
+guide_id: concept-economy
+language: en
+status: active
+use_when:
+  - naming anything lasting or shared — a feature, entity, type, field, flag, enum value, failure kind, artifact, or documentation term
+  - a review finding or test failure tempts you to add a name to make it go away
+  - deciding whether a value is its own concept or a property of an existing one
+  - deciding what a public surface exposes versus where the truth actually lives
+  - laying out a repository, or judging whether its shape still matches its concept graph
+core_rules:
+  - name the nearest existing concept before adding one, then choose reuse / extend / rename / split out loud
+  - every fix has a concept-surface sign — reducing, preserving, or increasing; say which before making it
+  - one value has one owner, and every other surface is generated from it rather than restated
+---
+
+# Concept Economy
+
+A scoped extension of the global Concept Economy section. Use it when you are about to introduce
+or change a name that will outlive the change that created it.
+
+The cost this guide manages is not disk or tokens. It is the reader's working set: every distinct
+name in a system is something a person or a model must hold, disambiguate, and keep aligned with
+its siblings. Two names for one behavior is not redundancy — it is a standing invitation to edit
+one and not the other, and that divergence is silent until something breaks in production.
+
+## What Counts As A Concept
+
+Anything **lasting or shared**. The list is deliberately long because the expensive additions are
+rarely the ones that feel like architecture:
+
+features, entities, variables, types, helper modules, artifacts, config keys, CLI flags, MCP/tool
+fields, public response fields, artifact fields, enum values, failure kinds, retry/recovery
+tokens, process names, documentation terms.
+
+What is *not* a concept: transient locals, generic containers (`items`, `result`, `tmp`), and
+layout a framework or tool imposes on you. The binding test is whether a second person has to
+learn the name to work here. A loop variable never crosses that line; a new failure kind always
+does, even when it is one string in one enum.
+
+The trap is scale-blindness. A field added to a response is one line of diff and a permanent
+addition to every consumer's mental model — including consumers you have not met.
+
+## The Four Paths
+
+Before adding or changing a concept, find the nearest existing one and choose a path **explicitly**.
+Choosing silently is how near-duplicates arrive: nobody decided to add a second name, they just
+did not look for the first.
+
+| Path | Choose it when | What you owe |
+| --- | --- | --- |
+| **Reuse** | an existing concept already covers this behavior | nothing — this is the default and needs no justification |
+| **Extend** | the existing concept covers it once you add a property | the property, and a check that existing readers tolerate its absence |
+| **Rename** | the behavior is right and the name has drifted from it | every site, in one change — a half-rename is strictly worse than either name |
+| **Split** | one of the split triggers below actually fired | the parent named, the reason stated, aliases mapped back |
+
+Prefer broad, stable concepts with precise properties over narrow near-duplicates. `Job` with a
+`kind` property beats `ImportJob` / `ExportJob` / `CleanupJob` as long as they share a lifecycle;
+the moment they stop sharing one, that is a split trigger, not a naming preference.
+
+### Finding the nearest concept
+
+The instruction to "find the nearest existing concept" fails when you search for the name you
+already have in mind — the name you invented will not be there, and its absence reads as
+permission. Search for the **behavior** instead:
+
+- Grep the vocabulary the concept would produce, not the concept: the enum values, the failure
+  strings, the field names, the log messages.
+- Read the nearest sibling's full definition, not its name. Names understate coverage; a type
+  called `Session` often already carries the lifecycle you were about to name separately.
+- Ask what would have to be true for the existing concept to be wrong here. If you cannot state
+  it as a behavioral difference, you are adding a synonym.
+- Check the terminology surface the repo already operates — a lexicon, a glossary, a domain
+  manifest — before the code. It is shorter and it is where the deliberate decisions live.
+
+If that search returns nothing, the addition is probably real. Record what you searched, because
+the next person will otherwise repeat it.
+
+## When To Split
+
+A split is warranted when the two things differ in something a caller can observe or must handle.
+These are the triggers; anything else is a preference:
+
+runtime behavior · ownership · lifecycle · validation · failure mode · user-visible behavior ·
+audit/replay requirements · authority · persistence · user control · failure handling
+
+Not triggers: a different call site, a different caller, a longer function, or a reviewer's
+discomfort. Those are reasons to add a property, a parameter, or a comment.
+
+When a split is necessary, three things ship with it or the split leaves debt:
+
+1. **Name the parent.** The concept being split from, explicitly, in the change.
+2. **State the reason.** Which trigger fired, in one sentence, where a maintainer will find it.
+3. **Map the variants back.** Aliases, deprecated spellings, and old values resolve to the
+   canonical concept — otherwise the old name lives on as a second concept nobody declared.
+
+## Derived Values Stay Derived
+
+A value that tools or code can compute from its source is a **property or projection** of that
+source, not a concept of its own. Persisting it creates a second authority that can disagree with
+the first, and it will: the source moves and the copy does not.
+
+The test is whether anything reads the stored value that could not have derived it. If the answer
+is no, the value is a cache at best and a contradiction at worst.
+
+**Authority is not visibility.** These are separate questions and conflating them produces both
+failure modes at once:
+
+| | Question | Wrong answer looks like |
+| --- | --- | --- |
+| Authority | where does the truth live, and who may change it | two writers, or a derived copy that outranks its source |
+| Visibility | what may a given surface see | an internal projection leaked into a public contract, now unchangeable |
+
+A public response may expose a bounded view — fewer fields, coarser precision, a rendered form —
+while the source concept or artifact remains the one truth location. That is a projection, and it
+is correct. What is not correct is treating the projection as the place to fix a wrong value.
+
+Keep internal projections and helper outputs internal unless public exposure is genuinely required
+by user behavior, a product contract, or artifact truth. An exposed field cannot be withdrawn on
+your schedule.
+
+## Reuse The Vocabulary Before Adding To It
+
+Enum values, failure kinds, retry/recovery tokens, and result/failure surfaces are concepts with
+unusually high blast radius: every consumer's branch coverage depends on the set being stable.
+Adding a value obliges every exhaustive reader to handle it; adding a near-synonym obliges them to
+handle it *and* to guess which one they will actually receive.
+
+Check the existing set first, and prefer an existing value whose meaning genuinely covers the case
+over a new one that describes it more precisely. Precision that fragments the set costs more than
+it buys.
+
+## Classifying A Fix
+
+Before fixing a review finding or a test failure, say which way the fix moves the active concept
+surface:
+
+- **Reducing** — the fix removes a name, merges a duplicate, or deletes a branch. Cheapest, and
+  usually available when the finding is "these two do the same thing".
+- **Preserving** — the fix changes behavior inside existing names. The normal case.
+- **Increasing** — the fix adds a name. Legitimate, but it must survive the four-paths question,
+  and a review finding is not by itself a reason to add a concept.
+
+This matters because review findings create pressure toward the increasing path: adding a flag, a
+kind, or a special case makes a finding disappear locally while widening the surface everyone else
+carries. Naming the direction before making the change is what keeps that trade deliberate.
+
+## Migration Compatibility
+
+**Use** fallback paths, compatibility shims, and deprecated alias normalization **when explicit
+migration compatibility is required** — the obligation runs both ways: required compatibility gets
+a shim, and nothing gets one as a default hedge. Each one is a second
+concept surface that must be maintained and eventually removed.
+
+When you add one, the removal condition ships with it: what has to be true for the shim to go, and
+where that is recorded. A compatibility path with no stated end becomes permanent architecture by
+attrition.
+
+## Keeping The Shape Navigable
+
+Let the repository's shape mirror its concept graph. A shared, lasting concept's canonical name
+should be traceable across every layer it appears in — path, module, type/interface, field, public
+API — so the structure is guessable from the concept name instead of from a translation table you
+have to already know.
+
+The working test: someone who knows the concept's name but not this repo should be able to guess
+the path, or find it with one grep. If finding it requires knowing that the concept is called one
+thing in the schema, another in the module, and a third in the URL, the layout has stopped being
+navigable and the names are doing damage rather than work.
+
+This binds shared concepts only. Transient locals, generic containers, and framework- or
+tooling-imposed layout may diverge, and forcing them to conform is its own kind of waste.
+
+## Domain Notes
+
+- **Ontology work.** Check existing entities and relations first — before adding, modifying,
+  removing, or relinking either; the graph is the
+  artifact whose value degrades fastest under duplication, because every added node multiplies the
+  edges a reader must consider.
+- **Code work.** Follow the naming patterns the repository already uses — the file first, then
+  its neighbors — and consolidate the variations
+  your own change introduced before calling it done. A change that leaves three spellings of one
+  idea has added two concepts regardless of intent.
+- **Comments and active docs.** Keep them aligned with current runtime behavior, failure
+  semantics, retry policy, ownership, and authority. A comment describing a superseded contract is
+  not stale documentation — it is a second, false authority, and it reads as current to anyone who
+  finds it first.

package/claude/guides/documentation-hygiene.md

@@ -0,0 +1,112 @@
+---
+guide_id: documentation-hygiene
+language: en
+status: active
+use_when:
+  - writing a comment, and deciding whether it earns its place
+  - recording why something changed, an alternative that was rejected, or a migration's rationale
+  - deciding whether an active document should link to a historical note
+  - authoring a rule, guideline, or instruction others will follow
+  - choosing where change history and implementation context belong
+core_rules:
+  - prose about the past and prose about the present need different addresses, not different tenses
+  - a comment earns its place by carrying what the code cannot say about itself
+  - phrase a rule as the behavior you want, because a prohibition describes everything except what to do
+  - a continuously overwritten "current state" file claims to be now and is no particular time
+---
+
+# Documentation Hygiene
+
+A scoped extension of the global Documentation Hygiene section. The subject is placement: **prose
+about the past and prose about the present need different addresses.**
+
+The cost this manages is misreading, not tidiness. A sentence describing how something used to
+work, sitting beside code that works differently now, reads as a present fact — to a person
+skimming and to a model retrieving. Nothing marks it as history except a tense, and a tense is not
+a signal anyone checks. Moving it is cheaper than maintaining the reader's suspicion.
+
+## The two addresses
+
+**Active surfaces** — runtime code, comments, the docs someone reads to operate the thing — carry
+current behavior, current decisions, current contracts, current authority, current failure
+handling. Nothing else.
+
+**Isolated paths** — `docs/`, `design/`, `archive/`, `deprecated/` or whatever the repository uses
+— carry backward-compatibility notes, deprecated behavior, migration rationale, historical
+alternatives, change narratives, and handoff logs.
+
+The test for any sentence: *if this stopped being true, would anyone notice?* Active surfaces are
+where the answer must be yes, because something breaks. History is where the answer is no, which
+is exactly why it must not sit in the first place.
+
+## Comments carry what the code cannot
+
+A comment earns its place by saying something the code cannot say about itself:
+
+- Non-obvious current behavior — why this looks wrong and is right.
+- An invariant a reader could break without noticing they broke it.
+- A constraint that comes from outside the file: a protocol, a rate limit, an ordering another
+  system depends on.
+- A risk that still applies. Not one that used to.
+
+What does not earn its place: restating the line below it, narrating the change that introduced it
+("changed this to fix the bug"), or describing a contract that has since moved. That last one is
+not stale documentation — it is a **second, false authority**, and to whoever reads it first it is
+simply the answer.
+
+Comments describing superseded behavior are the highest-yield deletion in most files. They are
+also the hardest to find, because nothing fails when they are wrong.
+
+## History has its own address
+
+When you have something worth recording that is not current behavior — why an alternative was
+rejected, what a migration was compensating for, what a session handed off — write it in an
+isolated path rather than beside the code.
+
+Two properties make such a record useful:
+
+- **It is written once.** A record that is edited whenever things change stops describing any
+  particular moment. If it must be updated, the honest move is a new record that supersedes the
+  old one, not an overwrite.
+- **It carries its own point in time.** A timestamp in the filename cannot rot, because the age is
+  on the label. A file called "current state" makes a claim it cannot keep.
+
+That second point generalizes past records. Any continuously overwritten "the state of things"
+document claims to be now and is, in practice, no particular time — the last person to touch it
+decided how current it is, and nobody else can tell. Where the underlying facts are derivable,
+give the reader the command that re-derives them instead of a number someone typed.
+
+## Linking back
+
+Link from active material to a historical note only when the current task needs that history, or
+when the reference genuinely helps a future maintainer — usually because the present design looks
+arbitrary without it.
+
+A link is a small permanent cost: it invites the reader to leave, and it must stay resolvable. An
+active document that links to five historical notes has partly become one.
+
+## Writing rules people follow
+
+Phrase a rule as the behavior you want, not as the thing you are afraid of. A prohibition
+describes everything except what to do, and leaves the reader to invent the positive form —
+usually at the moment they have the least attention to spare.
+
+- "Pin the interpreter when a bash-specific feature is needed" beats "don't rely on the default
+  shell".
+- "State the assumption you are proceeding under" beats "don't guess".
+
+Two more properties of a rule that survives contact:
+
+- **It says when it fires.** A rule with no trigger is advice, and advice is followed when
+  convenient.
+- **It says what it costs.** A rule whose expense is hidden gets quietly dropped the first time
+  someone is in a hurry, and nobody records that it was dropped.
+
+## Where change history belongs
+
+Prefer the established homes over inventing one per change: a changelog for released behavior, a
+current-state dashboard for architecture and risk, handoff notes for what a session left unfinished.
+
+Keep their jobs distinct. A changelog that accumulates design rationale becomes unreadable as a
+changelog; a dashboard that accumulates history stops being current. When a document starts
+answering a question it was not built for, that is a signal to split it, not to add a section.

package/claude/guides/gpt-prompting.md

@@ -114,5 +114,5 @@ Derived from the vendor's published prompting guidance for the `targets` models
 above. When a `targets` model changes, re-derive this guide from current vendor
 guidance rather than editing around the old rules — prompting guidance is
 version-bound, and the previous generation's advice inverted on this one.
-`scripts/check-prompting-targets.sh` fails when the launch config binds a model
+`launch/check-prompting-targets.sh` fails when the launch config binds a model
 this guide does not list.

package/claude/guides/learning-flow.md

@@ -18,9 +18,9 @@ The **light**, per-user, single-session capture flow: turn a lesson from the
 current session into a **learning** (prose + a JSON record) that (a) applies to
 the user's own next session and (b) reaches the org for curation. This is the
 counterpart of the **heavy** session-distill pipeline (`distill!`), which mines
-many sessions and is curator/power-user only. Terms follow the agent-bios
-`LEXICON.md`; the full routing framework is
-`design/session-distill/PLACEMENT-FRAMEWORK.md` (agent-bios repo).
+many sessions and is curator/power-user only. Terminology and the full routing
+framework are maintained in the agent-bios repo; the criteria this flow applies
+are stated below.
 
 Defer to the preset mission: if this session runs the **Session distill** preset
 (trigger `distill!`), that mission owns capture — do not also run this flow.
@@ -62,7 +62,7 @@ still-valid candidates are surfaced for the user's approval.
 
 ## Domain tagging (the curation join key)
 
-Suggest a `domain` from the registered vocabulary in `config/domains.json`
+Suggest a `domain` from the registered vocabulary in `compose/domains.json`
 (domain keys for domain-specific lessons, or a tier name like `core`/`infra`
 for a genuinely cross-cutting lesson); the user **confirms**. If unsure, use
 `unclassified` (never blocks capture — the curator assigns later). If no
@@ -86,7 +86,7 @@ match your host):
       | agent-bios learn --host <claude|codex>
 
 The script (capability boundary) owns `learning_id` / `created` / `schema_version`,
-validates against `config/learning.schema.json`, logs the JSON record, and writes
+validates against `learn/learning.schema.json`, logs the JSON record, and writes
 the lesson prose where THIS host loads it next session:
 - **Claude**: appended to the automation-owned personal learnings file, pulled in
   by the entry file's `@personal/learnings.md` import.

package/claude/guides/llm-capability-boundary.md

@@ -204,7 +204,12 @@ Use it per field or operation, not as a blanket replacement for LLM judgment.
 Use this procedure when designing a new LLM-assisted artifact or revising an
 existing one.
 
-1. Identify the canonical artifact and downstream consumers.
+1. Identify the canonical artifact and downstream consumers. When the consumer already
+   exists, read its **acceptance predicate**, not only its schema: the schema says which
+   fields may appear, and the predicate says which combinations are credited. A producer
+   designed against the schema alone can emit records that are valid and never
+   accepted — one record per event where the consumer judges one record per subject is
+   the common shape of this, and it survives every field-level check.
 2. Split fields into semantic fields, deterministic fields, provenance fields,
    and side-effect operations.
 3. Assign each field or operation one primary authority.

package/claude/guides/review-request.md

@@ -26,10 +26,11 @@ verification_focus:
 This guide is a scoped extension of the global Coding Guidelines. Use it when
 composing what you ask a reviewer for — the request, the evidence bar, the
 verdict shape. It does not cover when to review, how deep, or what counts as
-material (the staged-workflow guide's severity ladder and review loop own that),
-which reviewer kind to route to (the multi-model guide's convergence heuristic),
-or how to phrase a prompt for a given model family (the per-family prompting
-guides).
+material (the severity ladder and review loop in `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/coding-staged-workflow.md` own that),
+which reviewer kind to route to — the convergence heuristic in
+`${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/verification-discipline.md` owns that. Phrasing a prompt for a specific model
+family is out of scope here; where that guidance ships, the rule that needs it
+points at it.
 
 The rules below are derived from ~330 real multi-lens review sessions run in
 this environment. That corpus is one model family in practice, so nothing here
@@ -80,8 +81,9 @@ So state the floor in the request: **do not report a finding you would rate low.
 It will be discarded; spend the effort on a medium-or-above finding instead.**
 This is not a quality bar on the reviewer, it is a cost decision — the corpus
 shows the discard happens regardless, so the only question is whether you pay to
-generate it first. (What counts as each severity is the staged-workflow guide's
-ladder, not this guide's.)
+generate it first. (What counts as each severity is the ladder in
+`${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/coding-staged-workflow.md`, not
+this guide's.)
 
 ## Forbid carry-forward findings
 
@@ -128,7 +130,7 @@ nicely: the submit schema refuses output without them. The result is a corpus
 where reviewers are right about existence (0.3% of issues end unresolved after
 argument) and where "found nothing" is a verified statement rather than silence.
 
-This is the general rule from the capability-boundary guide applied to review:
+This is the general capability-boundary rule applied to review:
 when output must have a property, make it unavailable without it. If your review
 route has a schema, put the anchor there. If it does not, the demand belongs in
 the request — but expect the weaker result that a request-only rule gives you.

package/claude/guides/session-distill-workflow.md

@@ -2,13 +2,14 @@
 guide_id: session-distill-workflow
 language: en
 status: active
+audience: author
 use_when:
   - a session was launched with the Session distill preset (mission-injected)
   - the launcher nudge says enough sessions accumulated for a mining window
   - mining local Claude/Codex sessions for learnings absent from the corpus
   - promoting, incubating, or retiring items in the session-distill ledger
 core_rules:
-  - the ledger and HANDOFF are the SSOT; read them before touching the pipeline
+  - the ledger is the SSOT for state; read it before touching the pipeline
   - placement follows PLACEMENT-FRAMEWORK.md, never ad-hoc judgment
   - every promotion passes an explicit user-approval gate
   - global growth per round is hard-capped (~500 tokens) by a measured gate
@@ -17,19 +18,28 @@ core_rules:
 
 # Session-Distill Workflow
 
+**Requires an agent-bios checkout.** This runbook edits the corpus itself, so it
+names repo paths and runs repo scripts. On a packaged install those do not exist:
+say so and stop rather than following steps you cannot execute.
+
 Runbook for a session-distill run: mine recent main-context sessions,
 verify candidates, place them through the framework, and apply with the user.
 Everything durable lives in the agent-bios repo.
 
 ## Read first (SSOT)
 
-1. `design/session-distill/HANDOFF.md` — initiative state, prior decisions,
-   open threads. 2. `design/session-distill/PLACEMENT-FRAMEWORK.md` — the
-   placement authority (typology A–G, layers, admission bars, lifecycle).
-3. `design/session-distill/ledger.json` — cumulative item states
-   (placed / incubating / absorbed / retired) with provenance.
+1. `design/session-distill/ledger.json` — the initiative's state. Every item
+   carries its status (placed / incubating / incubating-G / absorbed /
+   adopted-no-text), strength, and provenance, so what is open, what was
+   promoted, and what is still incubating are all queries against this file.
+   Read state here and nowhere else: a count or a status written into prose is
+   correct on the day it is written and silently wrong afterwards.
+2. `design/session-distill/versions.json` — which closed mining window maps to
+   which commit, and therefore what a rollback restores.
+3. `design/session-distill/PLACEMENT-FRAMEWORK.md` — the placement authority
+   (typology A–G, layers, admission bars, lifecycle).
 
-## Stage 1 — Mine (pipeline in `scripts/session-distill/`)
+## Stage 1 — Mine (pipeline in `session-distill/`)
 
 Run in order; each stage reads the previous stage's `out/`:
 
@@ -73,7 +83,7 @@ Run in order; each stage reads the previous stage's `out/`:
   stdout/stderr channel contracts) → codex/ + ko/ mirrors.
 - Verify per layer, not just by diff: enforcement/gate fixture tests
   (non-vacuous — known-bad must fire), hook trigger positive/negative sets,
-  `scripts/check-parity.sh` exit 0 unpiped, prompting-target gate, then
+  `gates/check-parity.sh` exit 0 unpiped, prompting-target gate, then
   `agent-bios install` to activate and re-verify.
 
 ## Stage 4 — G-pass (principles, not directives)
@@ -95,6 +105,6 @@ Run in order; each stage reads the previous stage's `out/`:
 3. Register the corpus version: append {version = window end, commit = the
    corpus-close commit} to `design/session-distill/versions.json` — this is
    what the launcher's Versions & rollback screen offers — then run
-   `python3 scripts/session-distill/update-state.py --window-end <date>`
+   `python3 session-distill/update-state.py --window-end <date>`
    (nudge baseline) and `corpus-state.py project` (launcher status panel).
 4. Merge the branch, push, and confirm deployed state (`agent-bios verify`).

package/claude/guides/tooling-gotchas.md

@@ -62,6 +62,15 @@ depends on it, pin it explicitly instead of trusting the environment.
   early-exit consumers (`cmd | head -1` → SIGPIPE 141), so it is a per-command
   choice, not a global default. Does not apply when the final stage IS the
   assertion (`cmd | grep -q pattern`).
+- **Passthrough arguments in a CLI you author**: an option meant to carry
+  another command's own flags cannot use a greedy-but-dash-stopping arity —
+  Python's `nargs="+"` ends at the first token starting with `-`, so the
+  wrapped command's `--model x` lands on the next positional and the error
+  names a parameter the caller never mentioned. Use the parser's
+  everything-after form (`argparse.REMAINDER`). A bare `--` separator is a
+  second, separate trap: argparse consumes it as its own positional marker
+  before the remainder sees it, so the form every caller reaches for first is
+  the one that breaks — normalize it out of `argv` before parsing.
 - **Reserved parameter names**: assigning to reserved shell names (`UID`,
   `EUID`, `GID`, `PPID`) can invoke the bound system behavior instead of
   storing a value — silently changing process credentials mid-script. Use
@@ -99,12 +108,29 @@ depends on it, pin it explicitly instead of trusting the environment.
 
 ## Git operations
 
+- **A stale local base inflates the range**: before reasoning about what a branch
+  contains or opening a PR, `git fetch`, then ask against the remote rather than the
+  local tracking ref — `git log origin/<base>..HEAD` for which commits are yours, and
+  the merge-base form below for the diff. On a shared repo the local base lags until
+  you pull, so `<base>..HEAD` quietly folds in work that already merged. When a range
+  looks surprisingly large, suspect the base before the branch.
+- **"Mergeable" is measured against the base, not against siblings**: the platform
+  flag says each PR merges into the base, and two PRs can both be clean while
+  conflicting with each other. Before choosing a merge order, diff their changed-file
+  sets and simulate the sequence.
 - **Two-dot diff semantics**: `git diff A..B` is a direct snapshot
   comparison — unlike `git log A..B` it excludes nothing, so a lagging
   merge-base injects unrelated upstream changes into the diff. For PR/review
   diffs use `git diff origin/base...HEAD` (merge-base form); suspect this
   mechanism first when a diff looks too large or shows deletions in untouched
   files.
+- **Reverting a path is not undoing your edit**: `git checkout <path>` and
+  `git restore <path>` discard *every* uncommitted change in that file. Used
+  to remove a planted probe it also removes whatever else was in flight there,
+  and the loss is silent. Check `git diff <path>` first, or plant in a copy and
+  restore from that. The same asymmetry makes the restore step fragile: if the
+  probe can time out or abort, the restore must not be the next command in the
+  same invocation — put it where a failure cannot skip it.
 - **Dirty-worktree pulls**: before pulling into a worktree with
   staged/unstaged/untracked changes, fetch first and compare incoming paths
   against every dirty path; on overlap or a non-fast-forward, stop and clear