git-span 1.0.136 → 1.0.137

package/README.md

@@ -1,6 +1,6 @@
 # git span
 
-`git span` tracks implicit semantic dependencies in a git repository — line-range or whole-file anchors that participate in a coupling no schema, type, or test enforces. Each span names its anchors, optionally carries a `why` sentence defining the subsystem they collectively form (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 in a git repository — line-range or whole-file anchors that participate in a coupling no schema, type, or test 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.
 
 The primary CLI surface lives in `src/cli/mod.rs`. Run `git span --help` or `git span stale --help` for flag reference.
 

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.136" 
+.TH git-span 1  "git-span 1.0.137" 
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
 .SH NAME
@@ -18,32 +18,38 @@ Each
 .B span
 anchors the participating anchors and carries a durable
 .I why
-\[em] one prose sentence that names the relationship the anchored set holds
-and survives a rewrite of either side.
+\[em] one present-tense sentence that defines the subsystem the anchored set
+forms together and stays true across a rewrite of either side.
 .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.
-Name the relationship the anchors hold in one prose sentence, written so it
-survives a rewrite of either side.
-Describe the relationship in role\-words (\(lqthe doc,\(rq \(lqthe parser,\(rq
+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.
-For asymmetric relationships, name which side is normative:
-\(lqthe doc is the source of truth when they disagree.\(rq
-Do not restate the span name, embed incidental implementation details, or
-bundle ownership and review triggers in the why.
+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.
 .PP
 .B Re\-anchoring on drift.
 When
 .B git span stale
 reports drift, review the change at each anchor.
-If the relationship still holds, re-anchor with
+Because a why only defines, it is inherited across routine re-anchors: if the
+subsystem still holds, re-anchor with
 .B git span add
-and commit.
-If the relationship has changed, update the why with
+and commit, leaving the why alone.
+Rewrite it with
 .B git span why
-before re-anchoring.
+only when the subsystem itself has changed.
 .PP
 Each span is an ordinary tracked file under the span root (default
 .IR .span ,
@@ -101,7 +107,7 @@ 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\-why(1)
-Read or stage the span\*(Aqs why — a one\-sentence definition of the subsystem, flow, or concern the anchors collectively form
+Read or stage the span\*(Aqs why — one complete present\-tense sentence defining the subsystem the anchors form together
 .TP
 git\-span\-delete(1)
 Delete a span
@@ -123,7 +129,7 @@ Print this message or the help of the given subcommand(s)
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
 .SH VERSION
-v1.0.136
+v1.0.137
 .SH EXAMPLES
 Anchor a new span alongside a code change:
 .PP
@@ -132,8 +138,8 @@ Anchor a new span alongside a code change:
 git span add billing/charge-request-contract \e
     docs/api/charge.md#L40-L88 api/charge.ts#L30-L76
 git span why billing/charge-request-contract \e
-    -m "The doc states the request body shape the parser honors; \e
-the doc is the source of truth when they disagree."
+    -m "The charge request body shape is stated by the doc \e
+and honored by the parser that reads it."
 git add .span
 git commit -m "Wire checkout to charge API"
 .fi
@@ -147,7 +153,8 @@ git span add auth/token-contract --at HEAD \e
     packages/auth/token.ts#L88-L104 \e
     packages/auth/crypto.ts#L12-L40
 git span why auth/token-contract \e
-    -m "Token verification depends on signature verification."
+    -m "Session token verification checks signatures with the \e
+algorithm and key encoding the crypto helper defines."
 git add .span && git commit -m "Document token/crypto coupling"
 .fi
 .RE

package/package.json

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