git-span 1.0.141 → 1.0.145

package/README.md

@@ -1,22 +1,22 @@
 # git span
 
-`git span` tracks implicit semantic dependencies — line-range or whole-file anchors coupled by nothing a schema, type, test, or build/generator step enforces. Each span names its anchors, optionally carries a `why` — one present-tense sentence defining the subsystem they form together (recommended on every span), and surfaces drift via `git span stale` when those anchors diverge from their anchored state.
+`git span` tracks implicit semantic dependencies — line-range or whole-file anchors coupled by nothing a schema, type, test, or build/generator step enforces. Each span names its anchors, should carry a compact, decision-relevant `why`, and surfaces drift via `git span drift` when anchors diverge from their recorded state.
 
-The primary CLI surface lives in `src/cli/mod.rs`. Run `git span --help` or `git span stale --help` for flag reference.
+The primary CLI surface lives in `src/cli/mod.rs`. Run `git span --help` or `git span drift --help` for flag reference.
 
-### The stale cache
+### The drift cache
 
-`git span stale` (and related resolution paths) are backed by a single persistent cache: a SQLite database at `<common_dir>/span/store.db` (plus its `-wal` and `-shm` companions), implemented in `src/resolver/store/`. This is the whole on-disk cache footprint — remove `store.db*` to reset it. Setting `GIT_SPAN_CACHE=0` disables it for a run.
+`git span drift` (and related resolution paths) are backed by a single persistent cache: a SQLite database at `<common_dir>/span/store.db` (plus its `-wal` and `-shm` companions), implemented in `src/resolver/store/`. This is the whole on-disk cache footprint — remove `store.db*` to reset it. Setting `GIT_SPAN_CACHE=0` disables it for a run.
 
 The store is bounded by a byte high-water mark (256 MiB by default; override with `GIT_SPAN_STORE_MAX_BYTES` or `git config git-span.storeMaxBytes`), with transactional GC that runs only when a publish crosses the cap. It lives in the Git *common* directory, so it is shared across linked worktrees of one clone on one host; it is not shared cross-host or cross-clone. Earlier releases kept two separate caches (a `cache/v1/` filesystem trail store and a `stale-cache.db`); both were replaced by this one store and leave no files behind on a fresh clone.
 
 ### The shared executable-digest store
 
-A configured filter driver's resolved executable (e.g. a `git-lfs` install) is content-hashed to prove its identity as part of every state-token capture. That hash is a fact about a file on the local machine, not about any one repository, so it is memoized in a *second*, small, per-user SQLite database — separate from the per-repo stale cache above — at `$GIT_SPAN_CACHE_HOME/exe-digest.db`, defaulting to `$HOME/.cache/git-span/exe-digest.db` (mirrors the workspace's `$HOME/.cache/git-span/cargo-target/` per-user build-artifact directory). Every repository on a machine that shares the same filter executable reuses the same memoized digest instead of re-hashing it per clone. `GIT_SPAN_EXE_DIGEST_DB` overrides the database file path directly (useful for CI isolation). `GIT_SPAN_CACHE=0` disables this store too, exactly like the stale cache. Implemented in `src/resolver/core/exe_digest_store.rs`; safe to delete at any time (it is rebuilt lazily, fail-closed on any error — a missing or broken database just means every executable is re-hashed).
+A configured filter driver's resolved executable (e.g. a `git-lfs` install) is content-hashed to prove its identity as part of every state-token capture. That hash is a fact about a file on the local machine, not about any one repository, so it is memoized in a *second*, small, per-user SQLite database — separate from the per-repo drift cache above — at `$GIT_SPAN_CACHE_HOME/exe-digest.db`, defaulting to `$HOME/.cache/git-span/exe-digest.db` (mirrors the workspace's `$HOME/.cache/git-span/cargo-target/` per-user build-artifact directory). Every repository on a machine that shares the same filter executable reuses the same memoized digest instead of re-hashing it per clone. `GIT_SPAN_EXE_DIGEST_DB` overrides the database file path directly (useful for CI isolation). `GIT_SPAN_CACHE=0` disables this store too, exactly like the drift cache. Implemented in `src/resolver/core/exe_digest_store.rs`; safe to delete at any time (it is rebuilt lazily, fail-closed on any error — a missing or broken database just means every executable is re-hashed).
 
 ## Profiling
 
-Perf investigation tooling is documented in [`./docs/profiling.md`](./docs/profiling.md):
+Perf investigation tooling is documented in [Profiling `git span drift`](../../wiki/guides/profiling-git-span-drift.md):
 
 - **Flame graph capture** — `perf record` + `inferno-flamegraph` recipe for identifying hot functions.
-- **`--perf-trace <path>`** — opt-in per-anchor wall-clock CSV emitter for `git span stale`; CSV schema, usage constraints, and quick analysis snippets are documented there.
+- **`--perf-trace <path>`** — opt-in per-anchor wall-clock CSV emitter for `git span drift`; CSV schema, usage constraints, and quick analysis snippets are documented there.

package/man/git-span.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH git-span 1  "git-span 1.0.141" 
+.TH git-span 1  "git-span 1.0.145"
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
 .SH NAME
@@ -18,38 +18,42 @@ Each
 .B span
 anchors the participating anchors and carries a durable
 .I why
-\[em] one present-tense sentence that defines the subsystem the anchored set
-forms together and stays true across a rewrite of either side.
+\[em] compact, decision-relevant context shared by the anchored set.
 .PP
 The standing question at commit time: did this change create or rely on a
 coupling that is not visible from the lines themselves?
 .PP
 .B Writing the why.
-Write one complete sentence, in the present tense, that defines the subsystem
-the anchors form together: name the thing, then say what it does across the
-anchors.
-Give it a subject and a verb \[em] never a label followed by a colon \[em] and
-name the thing in role\-words (\(lqthe doc,\(rq \(lqthe parser,\(rq
-\(lqthe runbook,\(rq \(lqthe migration\(rq) rather than repeating filenames.
-A why is read when a hook surfaces it mid\-task, so make it specific enough
-that a reader who just edited one anchor can tell from the sentence alone
-whether their change lands inside the thing it names.
-Do not restate the span name or embed incidental implementation details, and
-keep invariants, caveats, ownership, and review triggers out of the why \[em]
-those belong in comments at the anchor sites, in commit messages, CODEOWNERS,
-and PR descriptions.
+Write one or two complete present\-tense clauses in role words. State the
+relationship and any decisive nonlocal authority, invariant, permitted difference,
+lifecycle state, evidence gate, or focused conditional verification. Labels such
+as \(lqAuthority:\(rq and \(lqRemoval gate:\(rq are optional but must introduce
+complete clauses. Include only facts relevant from every anchor. Omit the span
+name, incidental implementation detail, generic work orders, and CLI procedure.
 .PP
 .B Re\-anchoring on drift.
 When
-.B git span stale
-reports drift, review the change at each anchor.
-Because a why only defines, it is inherited across routine re-anchors: if the
-subsystem still holds, re-anchor with
+.B git span drift
+reports drift, review the change at each anchor and decide which side of the
+coupling changed deliberately \[em]
+.B git span history
+shows the commit timeline \[em] then bring the other side back into agreement
+before re\-anchoring: a doc anchor that lags a deliberately committed code
+change is updated to match.
+Re\-anchoring records the current content as the anchored baseline with no
+semantic check, so re\-anchoring over a live disagreement conceals it.
+When agreement would require a code change, when the doc may be the intended
+contract rather than a description, or when no deliberate commit explains
+the drift, surface the decision instead of re\-anchoring.
+Inherit the why only while it remains true. For a routine re-anchor, use
 .B git span add
-and commit, leaving the why alone.
+without changing the why.
 Rewrite it with
 .B git span why
-only when the subsystem itself has changed.
+when the relationship or lifecycle state changes. A satisfied gate authorizes
+its transition; revise or retire the why and every superseded anchor. Require scoped
+.B git span drift
+to report zero drift.
 .PP
 Each span is an ordinary tracked file under the span root (default
 .IR .span ,
@@ -97,7 +101,7 @@ Show the named span — its anchors, why, and config. Equivalent to the bare `gi
 git\-span\-list(1)
 List files and anchors currently tracked by a span
 .TP
-git\-span\-stale(1)
+git\-span\-drift(1)
 Report anchors whose content has drifted from their anchored state
 .TP
 git\-span\-add(1)
@@ -106,8 +110,11 @@ Add anchors to a span, writing the span file under the span root. Stage and comm
 git\-span\-remove(1)
 Remove anchors from a span, editing the span file under the span root. Stage and commit the change with `git add .span && git commit`
 .TP
+git\-span\-replace(1)
+Replace one anchor on a span with another address, in a single atomic transaction: either the old identity is retired and the new identity installed together, or nothing changes
+.TP
 git\-span\-why(1)
-Read or stage the span\*(Aqs why — one complete present\-tense sentence defining the subsystem the anchors form together
+Read or stage the span\*(Aqs why — one or two complete present\-tense clauses carrying decision\-relevant nonlocal context
 .TP
 git\-span\-delete(1)
 Delete a span
@@ -119,17 +126,17 @@ git\-span\-tree(1)
 Trace blast radius: render a clique\-grouped impact tree rooted at the files matched by the given paths/globs
 .TP
 git\-span\-merge\-driver(1)
-Resolve `.span/` merge conflicts structurally when invoked by git as a merge driver. Receives three clean blob temp files and the marker length from git. Resolves only what is structurally derivable without trusting the worktree (which may be mid\-merge); defers same\-anchor range/hash divergence by writing minimal conflict markers and exiting non\-zero so `git span stale \-\-fix` can finish authoritatively
+Resolve `.span/` merge conflicts structurally when invoked by git as a merge driver. Receives three clean blob temp files and the marker length from git. Resolves only what is structurally derivable without trusting the worktree (which may be mid\-merge); defers same\-anchor range/hash divergence by writing minimal conflict markers and exiting non\-zero so `git span drift \-\-fix` can finish authoritatively
 .TP
 git\-span\-history(1)
-Show a chronological timeline of a span file\*(Aqs git history: each commit where the span changed, rendered oldest→newest, with the content of any anchor that was added, modified, or removed, and an optional `current` entry describing how the working tree has drifted from HEAD
+Show a span\*(Aqs git history as a git\-log\-style timeline: newest\-first commit entries whose patches are real unified diffs of the span declaration and of each anchor\*(Aqs content at its declared address, with the span\*(Aqs live drift rendered before the first commit as a headerless diff. That drift is not working\-tree\-only: it covers every resolver layer `git span drift` reports, and each block names its observational layers on a `drift source` line. `HEAD` identifies the comparison layer; it does not by itself prove that the declaration or content change was committed. Source order is the resolver\*(Aqs: line ranges use Worktree → Index → Head, while whole\-file anchors use Index → Worktree → Head
 .TP
 git\-span\-help(1)
 Print this message or the help of the given subcommand(s)
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
 .SH VERSION
-v1.0.141
+v1.0.145
 .SH EXAMPLES
 Anchor a new span alongside a code change:
 .PP
@@ -163,7 +170,7 @@ Check for drift and inspect a span:
 .PP
 .RS 4
 .nf
-git span stale
+git span drift
 git span billing/charge-request-contract
 git span show billing/charge-request-contract
 .fi

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "git-span",
-  "version": "1.0.141",
+  "version": "1.0.145",
   "bin": "bin/git-span.exe",
   "man": [
     "man/git-span.1"
@@ -24,11 +24,11 @@
     "scripts/postinstall.js"
   ],
   "optionalDependencies": {
-    "git-span-darwin-arm64": "1.0.141",
-    "git-span-darwin-x64": "1.0.141",
-    "git-span-linux-arm64": "1.0.141",
-    "git-span-linux-x64": "1.0.141",
-    "git-span-win32-x64": "1.0.141"
+    "git-span-darwin-arm64": "1.0.145",
+    "git-span-darwin-x64": "1.0.145",
+    "git-span-linux-arm64": "1.0.145",
+    "git-span-linux-x64": "1.0.145",
+    "git-span-win32-x64": "1.0.145"
   },
   "repository": {
     "type": "git",