yigraf 0.1.0__tar.gz

yigraf-0.1.0/.claude/.gitignore

@@ -0,0 +1,4 @@
+# Machine-local Claude Code settings written by `yigraf install-claude-hooks`. The hook commands bake
+# in this clone's absolute interpreter path, so they're per-machine — kept out of git. A teammate
+# inherits the committed SKILL.md + AGENTS.md block and just re-runs `yigraf install-claude-hooks`.
+settings.local.json

yigraf-0.1.0/.claude/settings.local.json

@@ -0,0 +1,28 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"/Users/r1m9n/Documents/yigraf/.venv/bin/python3\" -m yigraf hook post-tool-use",
+            "timeout": 15
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"/Users/r1m9n/Documents/yigraf/.venv/bin/python3\" -m yigraf hook session-start",
+            "timeout": 15
+          }
+        ]
+      }
+    ]
+  }
+}

yigraf-0.1.0/.claude/skills/yigraf/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: yigraf
+description: Use when implementing or changing code in this repo to keep intent, code, and the reasoning behind it in sync. Before starting work, run `yigraf context "<topic>"` to surface governing intents, plans, prior decisions, and drift. After finishing a task, run `yigraf link <task> <symbol>` to name the symbols that implement it, and `yigraf remember` the non-obvious choices you made.
+---
+
+# yigraf — the intent↔code spine
+
+This repo is indexed by **yigraf**: one graph over code structure, intents (specs), plans, and the
+**memory** of why the code is the way it is — with enforceable links (`implements`, `concerns`)
+whose drift is surfaced when code and the thing that governs it diverge. A few rituals keep it
+useful — the hooks are a safety net, not a substitute.
+
+## 0. Orient before you touch code (always)
+Run `yigraf context "<what you're about to work on>"`. **This is the one command you need to read the
+graph** — the governing requirement(s), the implementing symbols (signature by default, full source
+when configured), the open tasks, the prior **decisions and their *why***, and any **drift** all come
+back through it, as a token-cheap map. Don't reach for a separate query or drift tool. If a spec
+already covers your change, refine it; don't duplicate. If a decision already settled the question,
+follow it (or `supersede` it on purpose).
+
+## 1. Link when a task is done (the seam)
+When you finish a task, name the symbols that implement it:
+`yigraf link task:<plan>/<n> sym:<path>#<name>` — this anchors the link to the symbol's current
+content. Linking once per completed task (not per edit) is enough.
+
+## 2. Capture the *why* (decisions & constraints)
+When you make a non-obvious choice — picked an approach over a named alternative, set a constraint,
+worked around something — persist the reasoning that `/clear` would otherwise lose. One line of why
+plus the rejected option is enough; capture at the *conclusion*, not mid-thinking.
+- `yigraf remember "<the decision, one line>" --type decision --why "<reasoning>" --serves int:<slug> --concerns sym:<path>#<name> [--rejected "<the alternative + why not>"]`
+- A correction or rule → `yigraf note-constraint "<rule>" --concerns sym:<path>#<name>` (flagged as a
+  candidate to promote into an enforced check).
+- Changed your mind? Never edit a decision in place — `yigraf supersede mem:<id> "<new decision>" --why "<what changed>"`. The old one stays as a rejected alternative.
+
+A `--concerns` link is **anchored** like `implements`: edit that code later and yigraf surfaces a
+"re-verify this decision still holds" reconcile. That's the payoff — the next agent to touch the code
+sees the decision and its rationale without reading the history.
+
+## 3. Author specs as you plan
+- `yigraf intent <slug> -s "The system SHALL …" --scenario "Given …, When …, Then …" [--design "…"]`
+- `yigraf plan <slug> -t "<title>" --task "<description>"` then `yigraf link task:<plan>/1 int:<slug>`
+  to track the intent.
+
+## 4. Drift means re-verify
+You don't poll for drift — `yigraf context` and the edit hook surface it for you: soft drift (a linked
+symbol's body changed) or hard drift (it's gone), for both `implements` (task→code) and `concerns`
+(decision→code) links. A pure rename auto-re-anchors. When drift surfaces, re-verify the code still
+satisfies the spec/decision, then `yigraf link` (or re-`remember` / `supersede` the decision) to
+re-anchor. (`yigraf drift` exits non-zero on drift — that's the commit/CI gate, not something you poll.)

yigraf-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,26 @@
+name: Release
+
+# Build + publish to PyPI on a published GitHub Release, via PyPI Trusted Publishing (OIDC) —
+# no API token stored anywhere. One-time setup on PyPI: project → Publishing → add a trusted
+# publisher (owner: mansilla, repo: yigraf, workflow: release.yml, environment: pypi).
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # OIDC token for trusted publishing
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Build sdist + wheel
+        run: uv build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

yigraf-0.1.0/.gitignore

@@ -0,0 +1,29 @@
+# --- Python ---
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# --- Environments ---
+.venv/
+venv/
+
+# --- OS ---
+.DS_Store
+
+# --- Reference clones (studied alongside yigraf; each carries its own .git history) ---
+# Not vendored or submoduled — kept out of yigraf's own repo. See origins/ on disk.
+origins/
+
+# --- Eval harness output (captured transcripts + per-arm settings; rebuildable) ---
+scripts/eval/runs/
+
+# --- Claude Code per-machine hook wiring ---
+# `yigraf install-claude-hooks` writes the absolute interpreter path into .claude/settings.local.json
+# (per-machine), which .claude/.gitignore keeps out of git. The shareable SKILL.md + AGENTS.md block
+# (and a future shared .claude/settings.json) ARE committed. See docs/caveats.md M5.

yigraf-0.1.0/AGENTS.md

@@ -0,0 +1,7 @@
+<!-- yigraf:start -->
+## yigraf
+This repo uses **yigraf** (a graph over code, intent, plan, and the *why*). Before changing code, run
+`yigraf context "<topic>"` — the one read command: it surfaces governing intents, prior decisions, and
+any drift to re-verify. After finishing a task, run `yigraf link task:<plan>/<n> sym:<path>#<name>`, and
+`yigraf remember` the non-obvious choices (with `--why` and `--concerns <sym>`).
+<!-- yigraf:end -->

yigraf-0.1.0/CLAUDE.md

@@ -0,0 +1,90 @@
+# yigraf — read this first
+
+**yigraf is a tool for AI coding agents, not for human beings.** Every surface it exposes — the CLI
+output, the hook injections, the error messages, the docs, this file — is designed to be *consumed by
+an agent*, optimized for an agent's constraints (a finite context window, a working memory wiped by
+`/clear`, no scrollback), and judged by whether it makes an agent's next action better. It is **not** a
+tool for a human to "understand the codebase," read the plan, or browse the design. A human is the
+*principal* whose intent yigraf carries; the **agent is the operator and the audience**.
+
+## The name
+
+**yigraf = "Why I Graph?"** It exists to answer, *for the agent*, the **why's** and **what-for's** of
+its current state — the questions an agent cannot answer from source alone and loses on every reset:
+
+- **What is this?** → `structure` (code symbols, files, calls — from tree-sitter)
+- **What is it *for*?** → `intent` (the SHALL/MUST contracts and goals it serves)
+- **What am I doing / what's left?** → `plan` (tasks in a DAG, with state)
+- **Why is it this way?** → `memory` (the decisions, constraints, and rejected alternatives)
+
+These four node families and the **cross-family edges** between them (`implements`, `tracks`,
+`serves`, `concerns`, `supersedes`) *are* the answer. Retrieval is "ask once, get the answer as a
+token-cheap slice." This is the whole product.
+
+## The design law (apply it to every change)
+
+When you add or change anything in yigraf, the test is **"is this better for the agent consuming
+it?"** — never "is this nicer for a human to read." Concretely, this is why the code looks the way it
+does, and the shape you must preserve:
+
+1. **Errors teach abandonment — so recoverable conditions exit 0 with guidance, not a stack trace.**
+   An unresolved locator, a near-duplicate, an existing name → `_guidance()` prints how to fix it and
+   exits `0`, so the agent reads it and retries instead of learning "this tool fails, stop calling it."
+   Only genuine stop-conditions (no workspace, the CI drift gate) exit non-zero. (`cli.py:_guidance`)
+2. **Output is for a context window, not a screen.** `context` returns locators + signatures (not
+   source by default), under a token budget, ranked — because the agent pays for every token and
+   re-reading what's already encoded is the waste yigraf exists to remove. (`retrieval.py`)
+3. **yigraf speaks *into* the agent's context, at the moment of action.** The value is delivered by
+   Claude Code hooks: `PostToolUse(Edit|Write)` injects the governing intent + drift for the file just
+   touched; `SessionStart(clear|compact)` re-injects the active plan + intents — *this is the
+   mechanism by which memory survives `/clear`*. (`cli.py:_post_tool_use`, `_session_start`)
+4. **Silence is a feature.** The edit hook returns `None` (injects nothing) unless the locus is
+   actually governed or has drift. Respect the agent's attention budget; never nag on a routine edit.
+   (`retrieval.py:context_for_locus`)
+5. **Fail-open, always.** A hook or a query must never block or break the agent's work — every hook
+   handler swallows exceptions and exits 0. (`cli.py:_run_hook`)
+6. **Files are truth; `graph.json` is a derived, recomputable projection.** Never write volatile state
+   (usage/last_seen) into the committed graph — it lives in the gitignored `.local/` sidecar.
+   (DESIGN.md R1)
+
+If a proposed change optimizes for human ergonomics at the cost of any of these, it is probably wrong
+for yigraf. State the agent-cost/benefit in the change, not the human-readability.
+
+## The working loop (what the agent does with yigraf)
+
+This is the loop the `yigraf` skill and `AGENTS.md` instruct an agent to follow on **any** repo:
+
+```
+yigraf context "<topic>"          # before touching code: governing intent, plan, prior why, drift
+… do the work …
+yigraf link task:<plan>/<n> sym:<path>#<name>   # name the symbols a task implements (anchors them)
+yigraf remember "<decision>" --why "…" --concerns sym:<path>#<name> [--rejected "…"]   # persist the why
+```
+
+`context` is the **one read command** — intent, plan, implementing signatures, prior decisions, and
+drift all come back through it. Don't reach for separate query/drift tools.
+
+## Developing yigraf itself
+
+yigraf is **self-hosted**: it indexes its own repo, so the loop above applies here too. Before
+changing code, run `uv run yigraf context "<topic>"` to surface the governing intent and prior
+decisions; after a task, `link` the symbols and `remember` the non-obvious choices.
+
+- **Run / test:** `uv sync`, then `uv run pytest` (fast, no network). `uv run yigraf --help`.
+- **Optional semantic recall:** `uv pip install -e '.[embeddings]'` (local `bge-small`). Absent ⇒
+  retrieval degrades to the lexical seeder; never a hard dependency.
+- **Docs:** the public references are [`README.md`](README.md) (overview, install, how-it-works) and
+  [`docs/language-support.md`](docs/language-support.md) (the tested capability matrix). The internal
+  design corpus (decision log, milestone notes, research) was removed from the repo; that history lives
+  in git, and the authoritative *current* state is the code, the tests, and this file.
+- **Layout:** package under `src/yigraf/` (src-layout is deliberate — `yigraf init` creates a data dir
+  named `yigraf/` at a repo root, and the two must not collide).
+- **Status:** v0 spine (M0–M6) + memory milestone (M7–M9) complete and self-hosted. Counters are
+  local + recomputable (v0); the shared/committed counter model is v1/Enterprise (cloud) work.
+
+## Conventions
+
+- Commit messages and PRs follow the harness footer rules (see the agent's commit guidance). Only
+  commit/push when asked.
+- Match the surrounding code: terse module docstrings that cite the governing decision (e.g. `R1`,
+  `M8`), dataclasses for results, no speculative abstraction.

yigraf-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ricardo Mansilla
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

yigraf-0.1.0/PKG-INFO

@@ -0,0 +1,222 @@
+Metadata-Version: 2.4
+Name: yigraf
+Version: 0.1.0
+Summary: A harness primitive for AI coding agents: one connected graph over code, intent, plan, and memory — legible (token-cheap retrieval) and enforceable (intent↔code drift checks).
+Project-URL: Homepage, https://github.com/mansilla/yigraf
+Project-URL: Repository, https://github.com/mansilla/yigraf
+Project-URL: Issues, https://github.com/mansilla/yigraf/issues
+Author-email: Ricardo Mansilla <rick.mansilla@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: agents,ai,claude,code-intelligence,knowledge-graph,llm,tree-sitter
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Requires-Dist: networkx>=3.4
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: tree-sitter-bash<0.25,>=0.23
+Requires-Dist: tree-sitter-c-sharp<0.25,>=0.23
+Requires-Dist: tree-sitter-c<0.25,>=0.23
+Requires-Dist: tree-sitter-cpp<0.25,>=0.23
+Requires-Dist: tree-sitter-go<0.26,>=0.23
+Requires-Dist: tree-sitter-java<0.25,>=0.23
+Requires-Dist: tree-sitter-javascript<0.26,>=0.23
+Requires-Dist: tree-sitter-kotlin<2.0,>=1.0
+Requires-Dist: tree-sitter-php<0.25,>=0.23
+Requires-Dist: tree-sitter-python<0.26,>=0.23
+Requires-Dist: tree-sitter-ruby<0.25,>=0.23
+Requires-Dist: tree-sitter-rust<0.25,>=0.23
+Requires-Dist: tree-sitter-scala<0.27,>=0.23
+Requires-Dist: tree-sitter-sql<0.4,>=0.3
+Requires-Dist: tree-sitter-swift<0.9,>=0.7
+Requires-Dist: tree-sitter-typescript<0.25,>=0.23
+Requires-Dist: tree-sitter<0.26,>=0.25
+Requires-Dist: typer>=0.12
+Provides-Extra: embeddings
+Requires-Dist: numpy>=1.24; extra == 'embeddings'
+Requires-Dist: sentence-transformers>=2.2; extra == 'embeddings'
+Description-Content-Type: text/markdown
+
+# yigraf
+
+> **yigraf — "Why I Graph?"** A tool **for AI coding agents, not for humans.** It answers, *for the
+> agent*, the **why's** and **what-for's** of its current state — the questions an agent can't recover
+> from source alone and loses on every `/clear`. A human is the *principal* whose intent it carries; the
+> agent is the operator and the audience.
+
+## What is yigraf?
+
+yigraf is a **harness primitive** for AI coding agents: it projects your repo into one connected graph
+over four kinds of knowledge —
+
+- **structure** — the code itself (*what is this?*)
+- **intent** — specs/requirements (*what is it for?*)
+- **plan** — goals and tasks (*what's left?*)
+- **memory** — decisions and their reasoning (*why is it this way?*)
+
+— and keeps them linked, so the right slice of an agent's work is both **legible** (scoped, token-cheap
+retrieval instead of re-reading files) and **enforceable** (an intent↔code *drift check* that fires when
+code and the thing governing it diverge). It retrofits onto an existing repo — `yigraf init` and go.
+
+The problem it solves: an agent's working memory is wiped on every `/clear`, and source code doesn't
+record *why* it's the way it is or *what* it's supposed to do. yigraf persists that context as a
+queryable graph and re-surfaces the relevant piece exactly when the agent needs it.
+
+### Capabilities
+
+- **Structure index** — tree-sitter parsing into file/module/symbol nodes with a reformatting-stable
+  content hash, across **16 languages** (see [`docs/language-support.md`](docs/language-support.md)).
+- **Intent & plan** — author specs and task plans as Markdown; link a task to the symbols that implement
+  it, **anchored** to their current content.
+- **Drift detection** — when anchored code changes, yigraf surfaces *"re-verify this still holds, then
+  re-link or supersede."* A pure rename re-anchors automatically; a body change is honest drift. (This is
+  the part that makes yigraf governance, not just an index.)
+- **Memory** — capture decisions + the reasoning behind them; recall by **meaning** (optional embeddings)
+  or lexically; a decision earns `settled` after surviving K commits un-superseded; `gc` archives churn.
+- **Token-cheap retrieval** — `yigraf context "<topic>"` returns a scoped, budgeted slice (locators +
+  signatures, not file dumps) — measured ≈2.5× cheaper than reading the file.
+- **Agent integration** — Claude Code hooks inject governing intent + drift on edit and re-inject the
+  plan after `/clear`; a skill teaches the rituals. The `yigraf` CLI works with any agent.
+
+### Requirements (and what each is for)
+
+| Requirement | Why |
+|---|---|
+| **Python ≥ 3.11** | yigraf runs as a Python CLI |
+| **A git repo** | drift anchoring and git-derived maturity read git history (degrades gracefully without git) |
+| **Tree-sitter grammars** | structure extraction — **bundled**, no setup |
+| **An agent harness** | Claude Code gets hooks + a skill out of the box; any other agent can drive the CLI |
+| **An embeddings backend** *(optional, `[embeddings]` extra)* | semantic recall of memory/intent by meaning; **falls back to lexical** retrieval if absent — never required |
+
+## Quickstart
+
+```bash
+# 1. install (see Installation for per-platform setup)
+uv tool install git+https://github.com/mansilla/yigraf.git
+
+# 2. in your repo: create the workspace and index the code
+cd your-repo
+yigraf init
+yigraf build
+
+# 3. wire it into Claude Code (hooks + skill)
+yigraf install-claude-hooks
+
+# 4. use it
+yigraf context "session expiry"          # a scoped, token-cheap slice for a topic
+yigraf intent session-expiry -s "The system SHALL expire a session after 30m idle."
+yigraf link task:auth/1 sym:src/auth/session.py#refresh   # anchor a task to its code
+yigraf remember "chose monotonic clock" --why "wall-clock skews under NTP"
+yigraf drift                             # report any intent↔code drift
+```
+
+## Installation
+
+yigraf installs from source (not yet on PyPI). It needs **Python ≥ 3.11**; the tree-sitter grammars are
+bundled, so there's nothing else to set up. Installing as an isolated tool (uv or pipx) is recommended.
+
+**Any platform — pick one:**
+
+```bash
+uv tool install git+https://github.com/mansilla/yigraf.git          # uv
+pipx install "git+https://github.com/mansilla/yigraf.git"           # pipx
+
+# with semantic recall (numpy + sentence-transformers):
+uv tool install "yigraf[embeddings] @ git+https://github.com/mansilla/yigraf.git"
+```
+
+### macOS
+
+```bash
+brew install uv          # or: brew install pipx ; and Python 3.11+ via `brew install python@3.12`
+uv tool install git+https://github.com/mansilla/yigraf.git
+```
+
+### Linux
+
+```bash
+# Debian/Ubuntu — ensure Python 3.11+ and git
+sudo apt-get update && sudo apt-get install -y python3 python3-venv git
+curl -LsSf https://astral.sh/uv/install.sh | sh        # install uv (or: pipx via your package manager)
+uv tool install git+https://github.com/mansilla/yigraf.git
+```
+
+### Windows
+
+```powershell
+winget install astral-sh.uv          # install uv
+winget install Git.Git               # drift anchoring uses git; install Git for Windows
+# (Python 3.11+ via `winget install Python.Python.3.12` if you don't have it)
+uv tool install git+https://github.com/mansilla/yigraf.git
+```
+
+### From source (development)
+
+```bash
+git clone https://github.com/mansilla/yigraf.git
+cd yigraf
+uv sync                  # create the venv + install deps (incl. dev tools)
+uv run yigraf --help
+uv run pytest
+```
+
+## How yigraf works
+
+yigraf projects your repo into one graph and keeps it in sync with the *why*:
+
+1. **Index** — `yigraf build` parses your code into file/module/symbol nodes, each with an
+   AST-normalized content hash (so reformatting and comments don't count as change).
+2. **Author** — write **intents** (specs) and **plans** (tasks) as Markdown; capture **memory**
+   (a decision + its reasoning) with `yigraf remember`.
+3. **Link** — `yigraf link <task> <symbol>` records which code implements a task and **anchors** the
+   link to that symbol's current content hash.
+4. **Retrieve** — `yigraf context "<topic>"` returns a scoped, token-budgeted slice: the governing
+   intents, the implementing symbols (as locators + signatures), prior decisions, open tasks, and any
+   drift — a small map, not a pile of file dumps.
+5. **Enforce** — when a symbol's anchored content changes, yigraf reports **drift** so the change gets
+   re-verified against what governs it (or the link re-anchored / the decision superseded).
+
+With Claude Code wired up (`yigraf install-claude-hooks`), steps 4–5 happen automatically: a
+**PostToolUse** hook injects governing intent + drift the moment the agent edits a governed file, and a
+**SessionStart** hook re-injects the active plan after a `/clear` — so a flow interrupted by a context
+reset resumes instead of restarting. The hook stays silent on ungoverned, undrifted edits (no nagging).
+
+## Files yigraf creates
+
+`yigraf init` lays down a `yigraf/` workspace at your repo root:
+
+```
+yigraf/
+├── config.yaml                 # committed — enabled languages, ignore globs, retrieval tunables
+├── intents/<slug>.md           # committed — requirement / goal / capability specs
+├── plans/{active,completed}/   # committed — plans + tasks (the filesystem is the state)
+├── memory/<id>-<slug>.md       # committed — decisions / constraints + the "why"
+├── graph.json                  # committed — the graph projection (recomputable state only)
+├── index/                      # gitignored — embedding index (rebuildable)
+├── cache/                      # gitignored — extraction cache
+└── .local/                     # gitignored — volatile telemetry (usage / last_seen)
+```
+
+The **committed** artifacts (`intents/`, `plans/`, `memory/`, `graph.json`, `config.yaml`) are the
+shareable record — they travel with the repo, so the next agent or teammate inherits the *why*. Derived
+and volatile state stays gitignored and rebuilds from source. yigraf also writes a self-contained
+`yigraf/.gitignore`, so nothing extra needs to be added to your repo's ignore rules.
+
+Two opt-in installers wire yigraf into your tooling:
+
+- **`yigraf install-claude-hooks`** — writes `.claude/settings.local.json` (machine-local hooks, *not*
+  committed) and `.claude/skills/yigraf/SKILL.md`.
+- **`yigraf install-hooks`** — adds a git **post-commit** hook that keeps `graph.json` synced to `HEAD`.
+
+## Language support
+
+16 languages, indexed at two depths (bespoke extractors for Python/Go/JS-TS, a generic tags-query tier
+for the rest). The full **tested** capability matrix — symbols / calls / imports / inheritance / drift,
+per language — is in **[`docs/language-support.md`](docs/language-support.md)**.

yigraf-0.1.0/README.md

@@ -0,0 +1,176 @@
+# yigraf
+
+> **yigraf — "Why I Graph?"** A tool **for AI coding agents, not for humans.** It answers, *for the
+> agent*, the **why's** and **what-for's** of its current state — the questions an agent can't recover
+> from source alone and loses on every `/clear`. A human is the *principal* whose intent it carries; the
+> agent is the operator and the audience.
+
+## What is yigraf?
+
+yigraf is a **harness primitive** for AI coding agents: it projects your repo into one connected graph
+over four kinds of knowledge —
+
+- **structure** — the code itself (*what is this?*)
+- **intent** — specs/requirements (*what is it for?*)
+- **plan** — goals and tasks (*what's left?*)
+- **memory** — decisions and their reasoning (*why is it this way?*)
+
+— and keeps them linked, so the right slice of an agent's work is both **legible** (scoped, token-cheap
+retrieval instead of re-reading files) and **enforceable** (an intent↔code *drift check* that fires when
+code and the thing governing it diverge). It retrofits onto an existing repo — `yigraf init` and go.
+
+The problem it solves: an agent's working memory is wiped on every `/clear`, and source code doesn't
+record *why* it's the way it is or *what* it's supposed to do. yigraf persists that context as a
+queryable graph and re-surfaces the relevant piece exactly when the agent needs it.
+
+### Capabilities
+
+- **Structure index** — tree-sitter parsing into file/module/symbol nodes with a reformatting-stable
+  content hash, across **16 languages** (see [`docs/language-support.md`](docs/language-support.md)).
+- **Intent & plan** — author specs and task plans as Markdown; link a task to the symbols that implement
+  it, **anchored** to their current content.
+- **Drift detection** — when anchored code changes, yigraf surfaces *"re-verify this still holds, then
+  re-link or supersede."* A pure rename re-anchors automatically; a body change is honest drift. (This is
+  the part that makes yigraf governance, not just an index.)
+- **Memory** — capture decisions + the reasoning behind them; recall by **meaning** (optional embeddings)
+  or lexically; a decision earns `settled` after surviving K commits un-superseded; `gc` archives churn.
+- **Token-cheap retrieval** — `yigraf context "<topic>"` returns a scoped, budgeted slice (locators +
+  signatures, not file dumps) — measured ≈2.5× cheaper than reading the file.
+- **Agent integration** — Claude Code hooks inject governing intent + drift on edit and re-inject the
+  plan after `/clear`; a skill teaches the rituals. The `yigraf` CLI works with any agent.
+
+### Requirements (and what each is for)
+
+| Requirement | Why |
+|---|---|
+| **Python ≥ 3.11** | yigraf runs as a Python CLI |
+| **A git repo** | drift anchoring and git-derived maturity read git history (degrades gracefully without git) |
+| **Tree-sitter grammars** | structure extraction — **bundled**, no setup |
+| **An agent harness** | Claude Code gets hooks + a skill out of the box; any other agent can drive the CLI |
+| **An embeddings backend** *(optional, `[embeddings]` extra)* | semantic recall of memory/intent by meaning; **falls back to lexical** retrieval if absent — never required |
+
+## Quickstart
+
+```bash
+# 1. install (see Installation for per-platform setup)
+uv tool install git+https://github.com/mansilla/yigraf.git
+
+# 2. in your repo: create the workspace and index the code
+cd your-repo
+yigraf init
+yigraf build
+
+# 3. wire it into Claude Code (hooks + skill)
+yigraf install-claude-hooks
+
+# 4. use it
+yigraf context "session expiry"          # a scoped, token-cheap slice for a topic
+yigraf intent session-expiry -s "The system SHALL expire a session after 30m idle."
+yigraf link task:auth/1 sym:src/auth/session.py#refresh   # anchor a task to its code
+yigraf remember "chose monotonic clock" --why "wall-clock skews under NTP"
+yigraf drift                             # report any intent↔code drift
+```
+
+## Installation
+
+yigraf installs from source (not yet on PyPI). It needs **Python ≥ 3.11**; the tree-sitter grammars are
+bundled, so there's nothing else to set up. Installing as an isolated tool (uv or pipx) is recommended.
+
+**Any platform — pick one:**
+
+```bash
+uv tool install git+https://github.com/mansilla/yigraf.git          # uv
+pipx install "git+https://github.com/mansilla/yigraf.git"           # pipx
+
+# with semantic recall (numpy + sentence-transformers):
+uv tool install "yigraf[embeddings] @ git+https://github.com/mansilla/yigraf.git"
+```
+
+### macOS
+
+```bash
+brew install uv          # or: brew install pipx ; and Python 3.11+ via `brew install python@3.12`
+uv tool install git+https://github.com/mansilla/yigraf.git
+```
+
+### Linux
+
+```bash
+# Debian/Ubuntu — ensure Python 3.11+ and git
+sudo apt-get update && sudo apt-get install -y python3 python3-venv git
+curl -LsSf https://astral.sh/uv/install.sh | sh        # install uv (or: pipx via your package manager)
+uv tool install git+https://github.com/mansilla/yigraf.git
+```
+
+### Windows
+
+```powershell
+winget install astral-sh.uv          # install uv
+winget install Git.Git               # drift anchoring uses git; install Git for Windows
+# (Python 3.11+ via `winget install Python.Python.3.12` if you don't have it)
+uv tool install git+https://github.com/mansilla/yigraf.git
+```
+
+### From source (development)
+
+```bash
+git clone https://github.com/mansilla/yigraf.git
+cd yigraf
+uv sync                  # create the venv + install deps (incl. dev tools)
+uv run yigraf --help
+uv run pytest
+```
+
+## How yigraf works
+
+yigraf projects your repo into one graph and keeps it in sync with the *why*:
+
+1. **Index** — `yigraf build` parses your code into file/module/symbol nodes, each with an
+   AST-normalized content hash (so reformatting and comments don't count as change).
+2. **Author** — write **intents** (specs) and **plans** (tasks) as Markdown; capture **memory**
+   (a decision + its reasoning) with `yigraf remember`.
+3. **Link** — `yigraf link <task> <symbol>` records which code implements a task and **anchors** the
+   link to that symbol's current content hash.
+4. **Retrieve** — `yigraf context "<topic>"` returns a scoped, token-budgeted slice: the governing
+   intents, the implementing symbols (as locators + signatures), prior decisions, open tasks, and any
+   drift — a small map, not a pile of file dumps.
+5. **Enforce** — when a symbol's anchored content changes, yigraf reports **drift** so the change gets
+   re-verified against what governs it (or the link re-anchored / the decision superseded).
+
+With Claude Code wired up (`yigraf install-claude-hooks`), steps 4–5 happen automatically: a
+**PostToolUse** hook injects governing intent + drift the moment the agent edits a governed file, and a
+**SessionStart** hook re-injects the active plan after a `/clear` — so a flow interrupted by a context
+reset resumes instead of restarting. The hook stays silent on ungoverned, undrifted edits (no nagging).
+
+## Files yigraf creates
+
+`yigraf init` lays down a `yigraf/` workspace at your repo root:
+
+```
+yigraf/
+├── config.yaml                 # committed — enabled languages, ignore globs, retrieval tunables
+├── intents/<slug>.md           # committed — requirement / goal / capability specs
+├── plans/{active,completed}/   # committed — plans + tasks (the filesystem is the state)
+├── memory/<id>-<slug>.md       # committed — decisions / constraints + the "why"
+├── graph.json                  # committed — the graph projection (recomputable state only)
+├── index/                      # gitignored — embedding index (rebuildable)
+├── cache/                      # gitignored — extraction cache
+└── .local/                     # gitignored — volatile telemetry (usage / last_seen)
+```
+
+The **committed** artifacts (`intents/`, `plans/`, `memory/`, `graph.json`, `config.yaml`) are the
+shareable record — they travel with the repo, so the next agent or teammate inherits the *why*. Derived
+and volatile state stays gitignored and rebuilds from source. yigraf also writes a self-contained
+`yigraf/.gitignore`, so nothing extra needs to be added to your repo's ignore rules.
+
+Two opt-in installers wire yigraf into your tooling:
+
+- **`yigraf install-claude-hooks`** — writes `.claude/settings.local.json` (machine-local hooks, *not*
+  committed) and `.claude/skills/yigraf/SKILL.md`.
+- **`yigraf install-hooks`** — adds a git **post-commit** hook that keeps `graph.json` synced to `HEAD`.
+
+## Language support
+
+16 languages, indexed at two depths (bespoke extractors for Python/Go/JS-TS, a generic tags-query tier
+for the rest). The full **tested** capability matrix — symbols / calls / imports / inheritance / drift,
+per language — is in **[`docs/language-support.md`](docs/language-support.md)**.