Initial publish v0.1.0: standalone workflow core (corpus + examples + guards)

core/rules/code-graph.md

@@ -0,0 +1,47 @@
+## Code Graph First (mandatory)
+
+Before any cross-file understanding or change, query the code graph first. Do
+NOT grep + read whole files to reconstruct relationships.
+
+- **Session start**: run `codegraph_status` to confirm the graph is built; if
+  empty, run `codegraph init -i` from the project root once. The graph persists
+  and is reused for the whole session.
+- **Trust but verify stats**: `codegraph_status` can return a stale or partial
+  snapshot. If counts look low, run `codegraph_status` again — codegraph
+  auto-syncs on file changes (2s debounce via native OS file watcher).
+  Do not run structural queries against a graph you suspect is incomplete.
+- **Structural questions** ("who calls / what depends on / where defined / what
+  breaks if I change this") MUST use `codegraph_explore` (primary, for flows and
+  surveys), `codegraph_search` (locate symbols), `codegraph_callers` (every call
+  site).
+  Do not piece relationships together from grep + read output.
+- **Reading an implementation**: use `read(filePath, symbol: "<name>")` to fetch
+  only the target symbol's line range. Do not read an entire large file to see
+  one function.
+- **grep is the fallback, not the default**: use grep only for fuzzy text the
+  graph cannot answer (comments, string literals, config text). Use
+  `codegraph_node` with `symbolsOnly: true` for a cheap structural overview instead of Glob.
+- **Delegate exploration**: prefer running graph + read inside an Explorer
+  subagent and returning only `file:line` results and conclusions, to keep the
+  main context lean.
+
+## Per-worktree indexes (mandatory for worktree sessions)
+
+The main checkout's `.codegraph/` indexes ONLY that tree. A git worktree lives
+outside the repo path, so nearest-`.codegraph/` resolution finds nothing under
+it — graph queries in a workflow worktree silently degrade to grep+read
+(the [org-internal #2561] / TD-006 gap).
+
+- `script/session-worktree.sh create` and `script/scratch-worktree.sh create`
+  build a per-worktree index automatically: `codegraph init -i <path>` runs in
+  the background (best-effort — missing CLI, existing index, or init failure
+  never blocks worktree creation). Set `CODEGRAPH_SKIP=1` to disable
+  (selftests / CI).
+- Worktrees created BEFORE this hook landed have no index: run
+  `codegraph init -i` once from inside them.
+- First query after creating a worktree may hit a still-building index; if
+  results look empty, check `codegraph status` inside the worktree, then retry.
+- Kickoff readiness (`checkCodegraph`) checks `<root>/.codegraph/codegraph.db`
+  per root, and `codegraph serve --mcp` resolves from the session's cwd — both
+  pick the worktree's own index once it exists.
+