graphite-code 1.2.0__tar.gz → 1.3.0__tar.gz

{graphite_code-1.2.0 → graphite_code-1.3.0}/CHANGELOG.md

@@ -15,6 +15,659 @@ machine-checkable identity; the version is for humans.
 
 ## [Unreleased]
 
+## [1.3.0] — 2026-10-16
+
+A minor release, with a security fix: from a folder below a repository's
+root, the agent hooks of 1.2.1 could take a directory another account made
+for the repository (see Security). Upgrade.
+
+JSON outputs that carry `schema_version` gain fields and codes, which are
+additions under `docs/compatibility.md`: a `no_path` result is graded
+(`answer`, `resolution`, `inconclusive`; #76); `check --json` gains the
+reason `below_repository_root` and the field `repository_root` (#81); and a
+Python `calls` answer may carry the caveats `python-member-call-bound-by-name`
+(#79) and `python-self-call-bound-for-enclosing-class` (#73). `--graph-json`
+left out below a repository root is now looked for at the root, and
+`docs/compatibility.md` records why that is a fix and not a change of
+default. `docs/reference/exit-codes.md` names the new failure and the new
+reason. No field is removed or renamed, `Requires-Dist` and the entry points
+are those of 1.2.1, and `graphite init` writes what it wrote (`DOC_VERSION`
+15).
+
+The graph changes in this release, in its edges only. On this repository,
+measured against the deployed 1.2.1 engine, with the same interpreter, from
+one tree:
+
+- all 9,031 node ids survive, each naming the same definition, file or
+  placeholder, and none is new;
+- `calls` goes from 15,811 to 15,771: 44 call triples are gone and 4 are
+  new. `contains` (6,502), `imports` (2,383) and `inherits` (120) are
+  unchanged, and 24,772 of 24,816 edge triples are unchanged;
+- `analysis` (20 cycles, entry points, god nodes, orphans) is identical. The
+  community count goes from 169 to 170;
+- the Python `calls` ratio is 0.976 before and after. The cell counts 40
+  fewer call sites (12,001 where there were 12,041), and 40 fewer bound, so
+  every site that left it had been bound.
+
+Two builds of this tree with either engine are byte-identical (`graph.json`,
+`GRAPH_REPORT.md`, `graph.html`). On a tree where two files of one language
+have the same content, the graph gains the file that had no node, with what
+it defines (#74).
+
+The entries below quote figures measured when each change was made, on
+earlier commits of this tree, so they differ from the ones above.
+
+### Added
+
+**A "no path" answer is graded (#76).** `reaches` and `path` answer an
+unreachable pair with the error `no_path`. Of everything those two verbs
+return it is the one result that asserts an absence, and nothing graded it.
+On a fixture where nine of a function's ten call edges are unbound, `callers`
+on a node answered `inconclusive` and `reaches` to that same node answered "no
+call path" as a plain error.
+
+A `no_path` result now carries three more fields:
+
+- `resolution`: how each end was matched, as a found path reports it;
+- `answer`: the block every other answer carries, scoped to the languages of
+  the two nodes the question resolved to;
+- `inconclusive`: true exactly when `answer.grade` is `inconclusive`.
+
+The grade is `inconclusive` where a cell the answer used is degraded or was
+not measured, and `advisory` otherwise. It is never `decision_grade`, for the
+reason an empty `callers` answer is not: a call the graph did not bind, or a
+caller registered as a callback, leaves a real path out of the graph, and no
+ratio can see an edge that was never emitted.
+
+Where one end was a pick between spellings (`Verdict` typed, a function
+`verdict` chosen), that end's `resolution` entry carries `case_ambiguous` and
+the answer carries the caveat `target-resolved-to-another-spelling`. Before
+this change the node id in the message was the only sign of the pick.
+
+Not changed: `error_code: no_path`, the message, `truncated` and `limits`. A
+`no_path` cut short by the depth bound still says `truncated: true`. Between
+two files that are not code there is nothing to grade by, and the result
+carries neither `answer` nor `inconclusive`, as before. The grade is taken
+from the two resolved nodes and never from the whole graph: grading a
+`no_path` against every language in the graph was the defect fixed on
+2026-07-31, and it is why such a result then carried no block at all.
+
+`graphite query` records a `query_inconclusive` incident for a `no_path`
+graded `inconclusive`, as it does for every other inconclusive answer. It
+used to skip every error result, which was right while a `no_path` was never
+graded. Such a result carries no `resolution_health`, so the incident's detail
+is the scoped cell and the grade (`answer calls(python) 0.1 inconclusive`).
+
+These are fields added to a JSON output that carries `schema_version`, which
+`docs/compatibility.md` makes a minor release. The sentences in
+`docs/agent-integration.md` and in the `query-result` schema that said a
+`no_path` is not graded are replaced with what it now carries.
+
+**`check --json` says when it was asked about a folder below a repository's
+root (#81).** The answer for such a folder, below the root of any Git
+repository whether graphite is set up in it or not, is `"reason":
+"below_repository_root"`, with one new field, `"repository_root"`: the
+directory to run it from, or `null` where the `.git` above is not one graphite
+takes (see Security). `stale` is `true` and the exit status is 1, as they
+were for that folder, and `added`, `changed`, `removed` and
+`resolution_health` are still there. `manifest` is not: it belongs to the
+reason `missing manifest`, which this answer replaces for such a folder, and
+no other reason carries it. The fix this belongs to is below.
+
+### Fixed
+
+**The strict graph-first hook sees a search behind a newline, a wrapper, a
+subshell, a fused regex escape or a variable (#75).** Each of these passed a
+search the hook refuses when it is written plainly. On a fixture with a
+function `dependents` in `src/`, `grep -rn dependents src/` was refused and
+every one of these was allowed:
+
+- **A later line.** `ls`, then `grep -rn dependents src/` on the next line. A
+  newline was read as a space, so the first word of the first line was the
+  head of the whole command. Most multi-line commands have this shape.
+- **A wrapper.** `sudo`, `env LC_ALL=C`, `time` and `command` before the
+  search; `ls src | xargs grep dependents`; `find src -type f -exec grep
+  dependents {} +`. Also read now: `nice`, `nohup`, `timeout`, and the shell
+  keywords a search follows (`if`, `then`, `do`, `!`, `{`). A `cd` behind one
+  of these is not followed: `env cd docs` moves a program that then exits, and
+  the shell stays where it was.
+- **A subshell.** `(grep -rn dependents src/)` and
+  `wc -l $(grep -rln dependents src/)`, in backticks and inside double quotes
+  as well. A subshell is read in the shell of the command that holds it. After
+  `cd docs && (...)` it searches `docs/`, and it reads the variables set
+  before it. Where it moves and what it sets stay inside it.
+- **A fused escape.** The Grep tool with `\bdependents\b` or `\sdependents`.
+  The escape and the name were read as one word, `bdependents`.
+- **A variable.** `P=dependents; grep -rn $P src/`. The hook now reads a
+  variable where the same command assigns it: through a chain
+  (`S=src; D="$S/pkg"; grep -rn dependents $D`) and in PowerShell
+  (`$p = 'dependents'`) as well. The value is dropped once something the hook
+  does not model may have set the variable again: a command that names it
+  (`read P`, `for P in ...`, `P+=...`), `source`, `.` and `eval`, or an
+  assignment after `&&` or `||`, which runs or does not.
+
+One more was not in the issue, and it hid a search on a single line too:
+
+- **A `#` inside a word.** `echo a#b; grep -rn dependents src/`, and
+  `[ $# -gt 0 ] && grep -rn dependents src/`. The lexer took any `#` for the
+  start of a comment and dropped the rest of the line, search and all. A
+  comment starts only at a `#` that starts a word.
+
+Three things changed with these, because reading every line made them matter:
+
+- **A pipeline runs where it started.** `cd docs && find . -type f | xargs
+  grep word` searches `docs/`. Every stage of a pipeline is read in the
+  directory the pipeline started in.
+- **A PowerShell path keeps its backslashes.** A PowerShell command was read
+  with the POSIX escape, so `-Path src\pkg\core.py` lost its backslashes,
+  named no file, and a search of that one file was refused. The backtick is
+  the escape there now.
+- **A PowerShell block comment is text.** What stands between `<#` and `#>`
+  is not read as commands.
+
+What is text stays text: the body of a heredoc, a PowerShell here-string,
+quoted strings and comments are not read as commands, so
+`git commit -m "$(cat <<'EOF' ... EOF)"` with a search quoted in the message
+is allowed as before. `graphite query ... | grep name` still filters. A search
+of one file, of a directory with no code, of a path outside the repository,
+and of a word that differs in case from the symbol are allowed on a later
+line and behind a wrapper exactly as they are when written plainly.
+
+A search on a later line is held to the rules a plain one is. One of them is
+that a search whose path the hook cannot read is refused when its pattern
+names a symbol: a path in a variable the hook could not expand, or a path
+after a `cd` it could not follow. Such a search on a later line was allowed
+only because the line was not read.
+
+Limits, stated in `docs/agent-integration.md`. Each of these is allowed, as it
+was:
+
+- a pattern in a variable set in the user's profile, by an earlier command,
+  from a command's output or as a prefix to the search itself
+  (`P=name grep $P`). The variable is not expanded, so the hook has no name
+  to check. A path in such a variable is the refused case above;
+- a search behind a wrapper flag that takes a word
+  (`sudo -u someone grep ...`), or with its tool named by a substitution
+  (`$(which grep) ...`);
+- a search in a command handed to another shell as a string
+  (`bash -c 'grep ...'`, `eval`);
+- a search in a shell function written on one line (`f() { grep ...; }`). A
+  body on lines of its own is read, whether or not the function is called;
+- a substitution inside the body of a heredoc. The body is read as text, and
+  where its delimiter is not quoted the shell runs a `$(...)` in it;
+- in PowerShell, files piped to `Select-String`
+  (`Get-ChildItem -Recurse src | Select-String name`). A command after a pipe
+  is read as a filter, `xargs` apart.
+
+The hook still fails open on a command it cannot read.
+
+**Two files with the same bytes each keep their place in the graph, and a
+moved file is named where it is (#74).** The extraction cache keyed an entry
+on a file's bytes and its language. What an entry holds names the file: every
+node id and every `source_file` in it is built from the path. So two files
+with the same bytes shared one entry, and one of them was answered with the
+other's nodes and had none of its own.
+
+- **On every build after the first**, one file of each such group was in the
+  graph and the others were not, with everything they define and every edge
+  from them. A tree of seven files, six of them in identical pairs (two
+  modules, two templates, two empty `__init__.py`), went from nine nodes to
+  five on a second build with nothing changed.
+- **On a first build** it was a race between worker threads, which is how the
+  issue was filed: one tree, built twice from an empty cache, gave two node
+  sets.
+- **An import of a package whose `__init__.py` is empty** pointed at a file
+  node that was not there, once another empty `__init__.py` had been read.
+- **A file moved with its bytes unchanged** kept its old path in the graph.
+  Python and TypeScript were spared, because the set of paths is already in
+  their key. Go, Rust, templates and every other file were not, and neither
+  were two Python files that exchange their contents.
+
+The issue was filed as file nodes with no edges coming and going. It was
+wider than that: definitions went with their file. Measured on Django 5.2.7,
+1.2.1 against this change, each built from an empty cache two or three times
+and then once more on the cache it had left:
+
+- 1.2.1 gave three different graphs, with 109, 110 and 118 files of a kind
+  the graph takes left without a node;
+- this change gave one graph four times, the same `graph.json` byte for byte.
+  Nothing a 1.2.1 graph holds is missing from it. It gains 128 to 137 nodes
+  and 166 to 168 edges, and 24 of the nodes are classes and functions in
+  Python files that had a twin.
+
+The file's path is now part of the key. An entry belongs to one file, an
+unchanged file is still answered from the cache, and nothing else about the
+cache changes. The first build after the upgrade extracts every file again,
+as after any change to the engine. On a tree where no two files of one
+language share their bytes the graph is what it was: this repository builds
+the same 8,655 nodes and 23,691 edges before and after.
+
+Five Django files still have no node, and none of them is this defect: three
+are binary, one is under a dot-directory, and one has the node id of another
+path beside it (`file_txt` and `file.txt`).
+
+**A Python member call is bound by what its receiver is, where the source
+says so (#79).** A member call (`obj.m()`) was bound by the name `m` alone: to
+every method of that name in the caller's file and the files it imports, up to
+three. So `Beta().setup()` was also a call to `Alpha.setup`, and
+`callers Alpha.setup` listed a function that only ever builds a `Beta`, at
+`decision_grade`. With one method of the name in reach the call was simply
+pointed at it: `f.read()` on a file opened on the line above was a call to
+the repository's one `read` method.
+
+Where the source states the receiver, that now decides:
+
+- **One class.** A class called to build the object (`Beta().m()`), the class
+  itself (`Beta.m()`), or a local name bound only from such a call
+  (`x = Beta()`, then `x.m()`) is bound to that class's own `m` and to nothing
+  else. The class may be defined in the file or imported by name.
+- **Not an object of the repository.** A literal (`", ".join(parts)`), the
+  result of a builtin that returns exactly a builtin type (`open(p).read()`,
+  `set(x).add(y)`), or a local name bound only from those
+  (`with open(p) as f:`) has no method the repository defines. The call gets
+  no edge.
+
+No edge, and not an `EXTERNAL_CALL` edge. That tag is for a call whose NAME
+is shown to leave the repository (`re.compile`, `expect`), and its placeholder
+node carries that name. Here the name on the edge is a local variable's
+(`f.read`), so a placeholder would say nothing, and for a literal the
+placeholder is a function of the module (`", ".join(x)` beside a `def join`),
+which is the false edge over again. No edge is also where a member call that
+binds to nothing already ends: the dispatch pass drops one with no method of
+the name in reach, and the noise list drops `parts.append(x)` before that. So
+these calls are not counted under `external`.
+
+A name is "bound only from" a value when every statement that binds it in its
+scope says the same; `None` is skipped, because it has no method to call.
+Flow is not followed.
+
+Bound by name as before: a parameter,
+annotated or not, because an annotation admits a subclass; an attribute
+(`self.x.m()`); what any other call returns; a method the stated class
+inherits and does not define; `a = b = Beta()` (only `b` is read);
+`(x := Beta())`; `y = x`; what `with Beta() as x` hands over; a builtin's
+name in a file with a star import, which may bind it; and `str(x)`,
+`repr(x)`, `format(x)` and `bytes(x)`, which return whatever the argument's
+own method returned. `self.m()` and `super().m()` are the next entry.
+
+Measured on Django 5.2.7 (2,224 Python files), with every member call of the
+1.2.1 engine set beside the same call under this change, and each receiver
+read a second time from CPython's own `ast`:
+
+- 201 calls on a builtin object that were bound to a method of the
+  repository have no edge (`"...".format()` was a call to
+  `NumberAwareString.format`, `s = set(); s.add(x)` to `Collector.add`);
+- 6 calls of a string's method that were recorded as calls to a module
+  function of that name have no edge;
+- 327 calls bound to their own class's method and to one or two others keep
+  the one;
+- 250 calls that had no edge, because more than three methods share the
+  name, are bound to their own class's method;
+- no call changed whose receiver the source does not state.
+
+On this repository: 3, 0, 45 and 3. The three are `read` called on an opened
+file, which had put two functions that only read a file among the callers of
+`Cache.read` (10 rows before, 8 now). `callers Cache.write` is unchanged at 17
+rows: it still lists a function that writes to a stream it is handed as a
+parameter. That row is false, it is bound by name, and the answer now says
+that a member call may be.
+
+What is still bound by name is now said on the answer: every Python `calls`
+answer carries the new caveat `python-member-call-bound-by-name`, next to
+`python-member-call-over-dispatch-cap`, which is the same pass over the cap.
+A new caveat code is an addition to a JSON output that carries
+`schema_version`.
+
+**`self.m()` and `super().m()` are bound by class, where the classes say
+which method runs (#73).** A call on `self` or on a bare `super()` was bound
+like any other member call, by the name `m` alone: to every method of that
+name in the caller's file and the files it imports when there are at most
+three, and to nothing when there are more. So `self.get_queryset()` in a
+class with a `get_queryset` of its own was a call to two other classes' as
+well; `super().__init__()` was a call to the `__init__` it is written in; and
+for the names many classes share (`__init__`, `get_queryset`, `to_dict`) the
+call had no edge at all. That last part is the issue as filed: since every
+method has a node of its own (1.2.0), more names are over the three.
+
+Python says which method runs: the first `m` in the linearisation of the
+object's class, from the class for `self` and after it for `super()`. The
+call is now bound to that method, for an object of the class the call is
+written in, where the classes graphite reads state which it is:
+
+- **Every base read.** Where each base of the class, and of its bases, is a
+  class graphite can read (a name that is a class of the file, or one
+  imported by name from the file that defines it), the linearisation is
+  computed as Python computes it (C3).
+- **A base not read.** A builtin, a dotted name (`models.Model`), a name
+  that reaches the file through a re-export, a call, a subscript. Such a
+  base may have an `m` of its own. It may also derive from a class that WAS
+  read, and Python then puts that class later than the readable bases
+  suggest: `class Child(Left, Right)`, `Left(Top)`, `Right(Unread)` reads as
+  Child, Left, Top, Right, and is Child, Left, Right, Unread, Top when
+  `Unread` derives from `Top`. So a method is bound only if what is written
+  puts its class before every other class that binds `m` and before every
+  base that was not read. What is written is two things Python keeps
+  whatever the rest is: a class comes before its bases, and the bases of a
+  class keep their order. So the class's own `m` is bound, and the first
+  base's (`class Child(Mixin, models.Model)`: `self.m()` is `Mixin.m`), and
+  a single chain up to the class whose base was not read.
+
+A method found this way is bound whatever file it is in and however many
+methods share its name. The reach rule and the cap of three exist to limit a
+guess by name, and here the bases are the evidence.
+
+**A class is more than the `def`s in its body.** Where the source shows
+another way for a class to get a method, the `def`s do not say which method
+runs, and the call is bound by name as before:
+
+- a decorated class on the way, its own `def` included. `@dataclass` makes
+  `__init__`, and any decorator may set or replace a name. No list of
+  decorators that leave a class alone is kept, and that has a price: an
+  engine that trusts every decorator binds 419 more calls on Django and 6
+  more on this repository. Telling such decorators from the rest is a
+  follow-up;
+- a class made with a keyword (`metaclass=M`, or any other but
+  `metaclass=type`) among the classes read, or an `__init_subclass__` on one
+  above the class: either runs for every class below it;
+- a class whose name its scope binds more than once: `C = deco(C)`, an
+  import of the name beside the class, or the class written twice under an
+  `if`, which is two classes and one node of the graph. Nothing is bound in
+  such a class, and for a class derived from it, it is a base that was not
+  read;
+- `m` set on one of the classes from outside its body in the same file
+  (`K.m = ...`, `del K.m`), or by one of its class methods (`cls.m = ...`);
+- a first class that binds `m` some other way than one `def` written
+  straight in its body: an assignment, a property object, two `def`s, a
+  `def` under an `if`, a `try`, a loop or a `with`, or under `global`;
+- for `self`: a method of any class read assigns `self.m`, because an
+  instance attribute shadows a method; or one of them has a
+  `__getattribute__`;
+- `m` behind a base that was not read, or nowhere among the bases:
+  `super().__init__()` under `class E(Exception)` is still a call to
+  whichever `__init__` methods are in reach;
+- a `__private` name, except on the class the call is written in;
+- `super(X, obj)` with arguments; `cls.m()` in a class method, in `__new__`,
+  `__init_subclass__` and `__class_getitem__`; a `self` that is given another
+  value; `super()` in a lambda, a nested function or a comprehension; a
+  `super` the file binds.
+
+**What is not read.** A call bound by class is bound to the method that
+runs where none of the following applies. graphite does not see these, and
+binds all the same:
+
+- anything behind a base that was not read. A metaclass, an
+  `__init_subclass__` or a decorator there can replace even the class's own
+  `def`, and a method there can assign `self.m`;
+- `setattr`, `K.__dict__`, `type(self).m = ...`, `self.__class__ = ...`, and
+  an assignment made in another file;
+- an alias: `me = self; me.m = f`, or `K = C; K.m = f`. Flow is not followed;
+- a decorator on a method. The call is bound to the `def`, whatever the
+  decorator returns, and the method the call is written in is taken to be
+  handed the instance, whatever decorates it;
+- a class decorator that returns a class with other bases than the one it
+  was handed;
+- a star import written after the class statement, which may bind its name
+  again.
+
+**Not followed: what runs for an object of a subclass.** For such an object
+`self.m()` runs an override below the class, and `super().m()` can reach a
+class the subclass added to its bases. Those edges are missing, and every
+Python `calls` answer says so with the new caveat
+`python-self-call-bound-for-enclosing-class`. Bound by name, an override was
+listed only where its file happened to be within reach, beside methods of
+unrelated classes. `python-member-call-over-dispatch-cap` and
+`python-member-call-bound-by-name` stay: calls on any other receiver are
+bound by name, and so are these wherever the classes do not state the
+method.
+
+Measured on Django 5.2.7 (2,224 Python files; 47,654 calls on `self` and
+1,705 on `super()`). Each of them under the engine before this change was
+set beside the same call after it, and the method that runs, for an object
+of the class the call is written in, was worked out from a fuller reading
+than the engine has: re-exports and dotted bases followed, builtin and
+standard-library classes taken as Python holds them, and "not known"
+wherever a class of the tree may get the method without a `def`.
+
+- 1,742 calls changed. 1,262 are now bound to exactly the method that runs.
+  425 are bound to the method the classes state under a standard-library
+  class whose own hook sets no method: 420 under `unittest.TestCase`, which
+  has an `__init_subclass__` since Python 3.11, and 5 under `abc.ABCMeta`.
+  For 55 the fuller reading still has a base it cannot read, or finds a
+  metaclass behind one, so what runs is not known, and they are bound as the
+  rule above says. Where the method that runs is known, no call bound by
+  class is bound to another.
+- 659 of them had no edge (609 with more than three methods of the name);
+  1,065 were bound to two or three methods and keep one; 18 were bound to
+  one method and are bound to another.
+- 1,332 bindings went. 271 were a `super()` call bound to the method it is
+  written in; 714 were methods of a class neither above nor below; 178 were
+  a base class's method behind the one that runs. 168 were an override in a
+  subclass, which does run for an object of that subclass: that is the loss
+  the new caveat names. One was a method whose name differs by case.
+- Of the 12,570 calls for which the fuller reading names a method of the
+  tree and no class on the way may get one without a `def`, 7,258 were bound
+  to exactly it before and 8,945 are now. 3,541 have no edge, and for 3,443
+  of those the one thing in the way is a base imported through a re-export
+  (`from django.test import TestCase`), which graphite does not read as a
+  class.
+
+The issue's table, on Django's `django/` package alone (15,563 member
+calls): calls with more than three methods of the name and no edge, 3,413
+before and 2,872 after; among them `self` calls 327 and 128, `super()` calls
+772 and 435. On this repository: 192 and 191, `self` calls 4 and 4. Those
+four are `self.to_dict()` in `@dataclass` classes: the price above, at home.
+
+`graphite impact <symbol>`, every definition asked of both graphs: on Django
+304 of 27,513 methods answer differently (89 lose an impacted file, 160 gain
+one; 32 lose a likely test, 47 gain one), with 9 of 10,546 class nodes and 9
+of 2,751 functions; on this repository 4 of 809 methods and nothing else.
+`impact <file>` is unchanged for every file of both. The built graphs keep
+their nodes: Django 854 edges gone and 653 new, this repository 15 and 1.
+The Python `calls` ratio is 0.697 before and 0.696 after on Django, because
+an edge bound by name to the wrong method counted as bound, and 0.976 on
+both sides here.
+
+Also in the test suite: classes made at random, some behind names graphite
+cannot read, some given a method by a decorator, a metaclass, a hook or an
+assignment, are run by Python itself, and each call graphite binds by class
+is held against the method that ran.
+
+**A call bound by name looks only in the files it can reach.** A Python
+call bound by name goes to the methods of that name in the caller's file and
+the files it imports. The engine found them by testing every method of the
+name, wherever it was, against that reach, and did so again for every call:
+in a tree where many classes share a name (`__init__`, `get`, `step`), what
+one call cost grew with the whole tree. The methods of a name are now held by
+the file they are in, and a call looks in its own file and the files it
+imports. The filter that keeps a call among the methods of its own language
+family, in every language, is worked out once for each name and family
+instead of once for each call.
+
+What a call is bound to is unchanged. The extraction of this repository, of
+two generated trees of 400 Python files of class hierarchies, and of a small
+tree that calls one name from Python and from TypeScript, which is now a
+test, is identical, node for node and edge for edge, under the engine before
+this change and after it. Measured once each, on one machine: extracting
+either generated tree takes 2.9 or 3.1 seconds where it took 4.3 or 4.5; and
+the test that holds each call bound by class against the method Python runs,
+which extracts such a tree, ran past the 120 seconds the CI run allows one
+test under Linux, Python 3.12 and coverage with branch measurement, and now
+takes 7 to 9 seconds there.
+
+**The CLI works from a folder below the repository root (#81).** A command
+took the directory it was typed in for the repository. One `cd` below the
+root, with the graph fresh at the root:
+
+- `query`, `search`, `context` and `impact` exited 1 with `graph unavailable:
+  graph_missing`, and `validate` with `graph not found`.
+- Each of those runs wrote a `.graphite/local/` ledger into the subfolder and
+  registered the subfolder as an open project, which no build can run in (the
+  failure 1.2.1 describes for the hooks).
+- `check .` said the graph was stale (`missing manifest`), which sends the
+  caller to a build. `build .` made `.cache/graphite/` in the subfolder and
+  was then refused with "nested Git roots are unsupported".
+
+The repository is now found by the rule the agent hooks have used since
+1.2.1 (#80): the nearest directory upward that holds `.git`, taken only where
+graphite is set up there (a `graph-out/graph.json`, or the `GRAPHITE.md` that
+`init` commits) and, new in this release for the hooks as well, only where it
+is the user's own (see Security). The rule is in one place,
+`ingest.repository_root`, and the hooks call it. In a folder of no checkout, and below a checkout graphite is
+not set up in, a read uses its own directory, as it did. A repository inside
+the repository, with its own `.git`, stays its own root.
+
+Below the root of a repository that is set up:
+
+- **Reads follow the root.** `query`, `search`, `context`, `impact`,
+  `validate` and `savings` answer from the repository's graph and say what
+  they say at the root.
+- **`--graph-json` left out is the repository's graph.** The option shows the
+  default it always showed, `graph-out/graph.json`, and
+  `docs/reference/cli.md` does not change. What changes is where that path is
+  looked for when the option is left out: at the repository's root, not in the
+  directory the command is typed in. `docs/compatibility.md` now records why
+  that is a fix and not a change of default. Typed out, the option means what it
+  meant: a path from the directory it is typed in, which must lie inside that
+  directory. The root's graph is never read in place of a file that was named.
+- **A file argument is read the way a shell reads it.** `context core.py`
+  typed in `app/` is `app/core.py`. A path from the root typed below it
+  (`context app/core.py` in `app/`) still works, and so does a node id or a
+  name; where both readings name a file, the one from the working directory
+  wins. Only a file is read this way, and from the text typed: no link is
+  followed. Beside `--graph-json` the arguments are left as typed.
+- **What a read records goes to the repository**: the usage ledger and the
+  `query_inconclusive` and `graph_load_failed` incidents. `incidents list`,
+  `ack` and `resolve` work on the ledger of the repository their path is in.
+  A `.graphite/` that these commands left in a subfolder under an earlier
+  version is no longer written or read by them, and can be deleted.
+- **A run registers the repository**, not the subfolder. Below a checkout
+  graphite is not set up in, a run now registers nothing, where it registered
+  a folder no build can run in.
+
+**`build`, `report`, `scan` and `check` name a path and do not follow the
+root.** Given a path below the root of any Git repository, set up for graphite
+or not, they stop before anything is written and say where the root is:
+"`<path>` is below the root of its Git repository; graphite builds and checks
+a repository from its root: run it from `<root>`". `check --json` still
+answers in JSON (see Added). Below a checkout graphite is not set up in, this
+too is new: `check .` used to say the graph was stale (`missing manifest`),
+and `build .` left `.cache/graphite/` behind before it was refused. Below a
+`.git` that is not the user's own, or one at a drive or filesystem root, they
+refuse as well but name no place to run (see Security).
+
+One thing changes at the root as well, because a file argument is read by one
+rule wherever it is typed: `context ./app/core.py`, and `context` given a
+whole path, did not find the file and now do. `impact` likewise.
+
+The agent hooks told a session below the root to run graphite from the root,
+every command of it. They now say that queries work from where the session
+is, and that a build or a check is run from the root.
+
+Not changed, and still wrong below a root: `doctor` given such a folder
+reports on the folder ("Graph artifact is missing", with `graphite build .`
+as the remedy), and its incident line reads the folder's own ledger, which
+nothing writes any more. `watch`, `review-changes` and the MCP server take
+the path or the directory they are given, as before.
+
+### Security
+
+**A repository root is taken from below it only when it is the user's own.**
+From a folder below a repository's root, the agent hooks since 1.2.1 and, in
+this release, the CLI's reads take the nearest directory upward that holds
+`.git` for the repository: they read its graph, write its ledger, and
+register it with the daemon, which then builds it. Nothing checked who owned
+that directory or its `.git`, so one made by another account on the same
+machine, anywhere above the folder, could be taken. Such a directory is now
+taken only when the user running graphite owns it and its `.git`, both as
+named and where a link to either leads (the owner of a link is whoever made
+it, and the hooks name the directory as the session does, links and all),
+and never when either is a drive or filesystem root. Anywhere else the
+folder stands for itself, as it did before 1.2.1 for the hooks and before
+this release for the CLI. `build`, `report`, `scan` and `check` still refuse
+below such a `.git`, and no longer name it as the place to run;
+`check --json` gives `"repository_root": null` there.
+
+Who owns a path is asked of the operating system (`graphite.ownership`): on
+POSIX the effective uid; on Windows the owner SID, which must be the user's,
+or the Administrators group while graphite runs with an elevated
+administrator's token. Where the owner cannot be read or is not the local
+user, as can happen on network shares and on volumes without permissions,
+or where a repository belongs to the Administrators group and the token is
+not elevated, or where graphite runs under `sudo`, the folder stands for
+itself: queries below the root then fail as they did before #81, and are run
+from the root instead.
+
+Found by aramid's review of #81, before release.
+
+## [1.2.1] — 2026-10-11
+
+A patch release. It carries one fix, to the agent hooks (#80). No stable
+surface in `docs/compatibility.md` changes: nothing under `docs/reference/` or
+`docs/schemas/` moves, `graphite agent-hook` still always exits 0, and the
+wording of a hook's message is not a stable surface. The graph itself does not
+change: on this repository, measured against the deployed 1.2.0 engine,
+8581 of 8581 node ids survive, 23612 of 23612 edge triples are unchanged,
+every relation count is equal, and `analysis` is identical. Only the engine
+fingerprint moves, because graphite's own bytes did.
+
+### Fixed
+
+**The agent hooks find the repository from a subfolder (#80).** A hook payload
+carries the session's directory, and in Claude Code that follows a `cd` in the
+shell. All three hooks took it for the repository root. One directory below the
+root, with the graph fresh at the root:
+
+- `session-start` said `Graph status: missing`, the status that licenses a full
+  fallback from graph-first. The remedy it printed, `python -m graphite build .`,
+  is refused there ("nested Git roots are unsupported").
+- `pre-tool-use` wrote nothing: no refusal in strict mode and no reminder. A
+  `cd` into any subfolder switched the gate off.
+- `stop` created a `.graphite/local/` in the subfolder for its cursor and looked
+  for the turn's usage there.
+- The subfolder was registered as an open project. The daemon cannot build
+  one, so it logged `project_snapshot_failed` for it at every discovery cycle,
+  and the repository's own marker was no longer renewed.
+
+The repository is now the nearest directory upward that holds `.git`, the test
+the build already uses to refuse a nested path (`ingest.enclosing_git_root`).
+It is taken only where graphite is set up: a `graph-out/graph.json`, or the
+`GRAPHITE.md` that `init` commits. In a subfolder of any other checkout, and in
+a directory outside every checkout, the hooks read the session's directory as
+they did. A repository inside the repository, with its own `.git`, stays its
+own root.
+
+One reading changes inside a checkout that is set up. A folder there that has
+its own `GRAPHITE.md` or `graph-out/` but no `.git` was read as a project of
+its own: `Graph status: missing`, or `unknown` over a leftover graph, with a
+`build .` that is refused there. It is now read as part of the checkout.
+
+Below the root:
+
+- The graph, the freshness check, the usage ledger and the activation marker
+  are the repository's.
+- A search's relative paths, and a search that names no path, belong to the
+  directory the shell is in. `grep <symbol> core.py` beside the file is one
+  file. A search with no path in a `docs/` that holds no code is text. `..` and
+  `../src` are judged as the directories they are.
+- Once the command line has run a `cd` the hook does not follow, or any command
+  it does not model, the shell may be anywhere in the repository. A search then
+  keeps an absolute path, and a relative one that names a file in the session's
+  directory. With a directory, or no path, it is judged as a search of the
+  whole repository: from a `docs/` with no code, `cd ../src ; grep -rn <symbol> .`
+  is refused. At the root this case resolves paths against the root, as before.
+- Every status, refusal and reminder ends by naming the root: "This session is
+  below the repository root: run graphite from `<root>`." The CLI still looks
+  for the graph in its own working directory (#81), so the commands those
+  messages print work from the root only.
+
+The hooks no longer register a directory below a checkout's root with the
+daemon, whether or not graphite is set up in that checkout.
+
+Nothing changes for a session at the repository root. Measured on the 1.2.0
+wheel and on this change: 32 strict-hook arms from the #72 work (25 refused, 7
+allowed) and 12 hook arms on a checkout with `.git` and `GRAPHITE.md` read the
+same on both.
+
 ## [1.2.0] — 2026-10-10
 
 A minor release. Query and search results, channel rounds and Python