gitnexus 1.6.10-rc.99 → 1.6.10

package/skills/gitnexus-refactoring.md

@@ -13,9 +13,32 @@ description: "Use when the user wants to rename, extract, split, move, or restru
 - "Move this to a new file"
 - Any task involving renaming, extracting, splitting, or restructuring code
 
+## Bind the repository first
+
+Refactoring writes to disk. `rename` with `dry_run: false` edits files in
+whichever repository was resolved, so binding identity here is a safety gate,
+not bookkeeping.
+
+Call `list_repos {}` before the first tool call. With one indexed repository,
+use the examples below as written. With more than one, pass `repo` on every
+call: an omitted `repo` normally errors, but under an MCP policy with a
+configured default it resolves to that default silently. If you cannot tell
+which repository is meant, stop and ask. Never run `rename` with
+`dry_run: false` until the preview in the same bound repository has been
+reviewed — its returned `file_path` values show which checkout is about to be
+written, so read them as a confirmation of identity.
+
+`list_repos` is paginated, so page with `offset: pagination.nextOffset` until
+`hasMore` is false before concluding a repository is absent.
+
+`detect_changes` takes `worktree` when you are editing a linked worktree the
+MCP server was not launched from; otherwise `git diff` runs in the wrong
+checkout and reports nothing changed, which reads as a verified refactor.
+
 ## Workflow
 
 ```
+0. list_repos {}                                  → Bind repo (and worktree)
 1. impact({target: "X", direction: "upstream"})  → Map all dependents
 2. query({search_query: "X"})                            → Find execution flows involving X
 3. context({name: "X"})                           → See all incoming/outgoing refs
@@ -29,7 +52,9 @@ description: "Use when the user wants to rename, extract, split, move, or restru
 ### Rename Symbol
 
 ```
+- [ ] list_repos {} — bind repo; explicit repo when >1 indexed, ask if ambiguous
 - [ ] rename({symbol_name: "oldName", new_name: "newName", dry_run: true}) — preview all edits
+- [ ] Confirm the previewed file paths are in the bound repository/worktree
 - [ ] Review graph edits (high confidence) and text_search edits (review carefully)
 - [ ] If satisfied: rename({..., dry_run: false}) — apply edits
 - [ ] detect_changes() — verify only expected files changed
@@ -39,6 +64,7 @@ description: "Use when the user wants to rename, extract, split, move, or restru
 ### Extract Module
 
 ```
+- [ ] list_repos {} — bind repo; explicit repo when >1 indexed, ask if ambiguous
 - [ ] context({name: target}) — see all incoming/outgoing refs
 - [ ] impact({target, direction: "upstream"}) — find all external callers
 - [ ] Define new module interface
@@ -50,6 +76,7 @@ description: "Use when the user wants to rename, extract, split, move, or restru
 ### Split Function/Service
 
 ```
+- [ ] list_repos {} — bind repo; explicit repo when >1 indexed, ask if ambiguous
 - [ ] context({name: target}) — understand all callees
 - [ ] Group callees by responsibility
 - [ ] impact({target, direction: "upstream"}) — map callers to update
@@ -64,7 +91,7 @@ description: "Use when the user wants to rename, extract, split, move, or restru
 **rename** — automated multi-file rename:
 
 ```
-rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: true})
+rename({symbol_name: "validateUser", new_name: "authenticateUser", repo: "my-app", dry_run: true})
 → 12 edits across 8 files
 → 10 graph edits (high confidence), 2 text_search edits (review)
 → Changes: [{file_path, edits: [{line, old_text, new_text, confidence}]}]
@@ -73,7 +100,7 @@ rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: true
 **impact** — map all dependents first:
 
 ```
-impact({target: "validateUser", direction: "upstream"})
+impact({target: "validateUser", repo: "my-app", direction: "upstream"})
 → d=1: loginHandler, apiMiddleware, testUtils
 → Affected Processes: LoginFlow, TokenRefresh
 ```
@@ -87,6 +114,14 @@ detect_changes({scope: "all"})
 → Risk: MEDIUM
 ```
 
+`partial: true` (a graph query failed) or `truncated: true` (the changed-symbol
+listing was capped) means the result is short of the truth: a short or empty
+list is not proof that only the expected files changed. Re-run it rather than
+treat the refactor as verified.
+
+A wrong-worktree zero carries neither flag and is indistinguishable from a
+clean verification, so confirm the diffed checkout is the one you edited.
+
 **cypher** — custom reference queries:
 
 ```cypher
@@ -102,20 +137,28 @@ RETURN caller.name, caller.filePath ORDER BY caller.filePath
 | Cross-area refs     | Use detect_changes after to verify scope  |
 | String/dynamic refs | query to find them               |
 | External/public API | Version and deprecate properly            |
+| Same name in another indexed repo | Bind `repo`; verify previewed paths before applying |
 
 ## Example: Rename `validateUser` to `authenticateUser`
 
 ```
-1. rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: true})
+0. list_repos {}
+   → total: 2 (my-app, billing-api) — both define validateUser, so bind explicitly
+
+1. rename({symbol_name: "validateUser", new_name: "authenticateUser", repo: "my-app", dry_run: true})
    → 12 edits: 10 graph (safe), 2 text_search (review)
    → Files: validator.ts, login.ts, middleware.ts, config.json...
 
 2. Review text_search edits (config.json: dynamic reference!)
 
-3. rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: false})
+3. rename({symbol_name: "validateUser", new_name: "authenticateUser", repo: "my-app", dry_run: false})
    → Applied 12 edits across 8 files
 
-4. detect_changes({scope: "all"})
+4. detect_changes({scope: "all", repo: "my-app"})
    → Affected: LoginFlow, TokenRefresh
    → Risk: MEDIUM — run tests for these flows
+   Repository: my-app (/abs/path/my-app)  Worktree: same  Index: current
 ```
+
+With a single indexed repository, step 0 returns `total: 1` and the `repo`
+argument drops out of every call above.

package/skills/gitnexus-review/SKILL.md

@@ -120,10 +120,17 @@ and do not claim a complete graph-backed review.
    review surface: when the diff changes what gets emitted or persisted,
    verify every schema/version constant gating caches, incremental
    writebacks, and fingerprint baselines was bumped or regenerated — in
-   GitNexus itself, for example: `INCREMENTAL_SCHEMA_VERSION` (the
-   incremental write set covers only changed files, so new cross-file edges
-   never reach an existing index without the bump), the parse-store
-   `SCHEMA_BUMP`, and both bench fingerprint sets.
+   GitNexus itself, for example: graph DDL needs no manual bump, because
+   `SCHEMA_FINGERPRINT` (`gitnexus/src/core/lbug/schema.ts`) is derived
+   from `NODE_SCHEMA_QUERIES` + `REL_SCHEMA_QUERIES` and moves on its own;
+   the check there is whether the diff changed any string in those arrays,
+   and, if it added a new DDL array, whether that array was folded into the
+   fingerprint. The hand-maintained ritual still applies where no
+   declarative artifact describes the invalidated set: the parse-store
+   `SCHEMA_BUMP` and both bench fingerprint sets still need an explicit
+   bump, re-checked against the base branch right before merge. Semantic
+   changes that leave the DDL untouched are outside the fingerprint; they
+   rely on the analyzer runner-identity receipt in the index metadata.
 
 ## Expert lenses
 
@@ -181,8 +188,7 @@ dropping anything without a concrete failing scenario.
 ### Swarm lanes
 
 Six dispatchable lane definitions ship with this skill in `ci-personas/` —
-read-only reviewers restricted to Read/Glob/Grep plus the safe graph
-tools. Five are finder lanes: `ci-correctness-lens`, `ci-security-lens`,
+read-only reviewers restricted to file reads plus the safe graph tools. Five are finder lanes: `ci-correctness-lens`, `ci-security-lens`,
 `ci-blast-radius-lens`, `ci-coverage-lens`, and `ci-adversarial-lens`
 (which assumes the change is broken and constructs reachable failure
 scenarios the pattern checks miss). They carry the verification

package/skills/gitnexus-review/ci-personas/ci-adversarial-lens.md

@@ -1,7 +1,7 @@
 ---
 name: ci-adversarial-lens
 description: CI review swarm lane. Assumes the change is broken and constructs concrete failure scenarios — races, hostile inputs, state corruption, abuse of new surfaces — verified against source and the GitNexus graph. Read-only; reports findings only.
-tools: Read, Glob, Grep, mcp__gitnexus__query, mcp__gitnexus__context, mcp__gitnexus__impact, mcp__gitnexus__explain, mcp__gitnexus__pdg_query, mcp__gitnexus__trace, mcp__gitnexus__list_repos
+tools: Read, mcp__gitnexus__query, mcp__gitnexus__context, mcp__gitnexus__impact, mcp__gitnexus__explain, mcp__gitnexus__pdg_query, mcp__gitnexus__trace, mcp__gitnexus__list_repos
 maxTurns: 12
 ---
 

package/skills/gitnexus-review/ci-personas/ci-blast-radius-lens.md

@@ -1,7 +1,7 @@
 ---
 name: ci-blast-radius-lens
 description: CI review swarm lane. Maps a PR's blast radius — dependents outside the diff, API/route surface, schema and version constants, compatibility breaks — from the GitNexus graph. Read-only; reports findings only.
-tools: Read, Glob, Grep, mcp__gitnexus__impact, mcp__gitnexus__api_impact, mcp__gitnexus__route_map, mcp__gitnexus__context, mcp__gitnexus__query, mcp__gitnexus__shape_check, mcp__gitnexus__tool_map, mcp__gitnexus__list_repos
+tools: Read, mcp__gitnexus__impact, mcp__gitnexus__api_impact, mcp__gitnexus__route_map, mcp__gitnexus__context, mcp__gitnexus__query, mcp__gitnexus__shape_check, mcp__gitnexus__tool_map, mcp__gitnexus__list_repos
 maxTurns: 12
 ---
 

package/skills/gitnexus-review/ci-personas/ci-correctness-lens.md

@@ -1,7 +1,7 @@
 ---
 name: ci-correctness-lens
 description: CI review swarm lane. Hunts logic errors, edge cases, contract breaks, and state bugs in the changed symbols of a PR, grounded in the GitNexus graph. Read-only; reports findings only.
-tools: Read, Glob, Grep, mcp__gitnexus__query, mcp__gitnexus__context, mcp__gitnexus__impact, mcp__gitnexus__pdg_query, mcp__gitnexus__trace, mcp__gitnexus__list_repos
+tools: Read, mcp__gitnexus__query, mcp__gitnexus__context, mcp__gitnexus__impact, mcp__gitnexus__pdg_query, mcp__gitnexus__trace, mcp__gitnexus__list_repos
 maxTurns: 12
 ---
 

package/skills/gitnexus-review/ci-personas/ci-coverage-lens.md

@@ -1,7 +1,7 @@
 ---
 name: ci-coverage-lens
 description: CI review swarm lane. Judges whether a PR's changed behavior is actually tested — missing cases, weak assertions, stale baselines, drift guards — using the GitNexus graph's test linkage. Read-only; reports findings only.
-tools: Read, Glob, Grep, mcp__gitnexus__query, mcp__gitnexus__context, mcp__gitnexus__impact, mcp__gitnexus__check, mcp__gitnexus__list_repos
+tools: Read, mcp__gitnexus__query, mcp__gitnexus__context, mcp__gitnexus__impact, mcp__gitnexus__check, mcp__gitnexus__list_repos
 maxTurns: 12
 ---
 

package/skills/gitnexus-review/ci-personas/ci-critic-lens.md

@@ -1,7 +1,7 @@
 ---
 name: ci-critic-lens
 description: CI review swarm gate. Audits the orchestrator's draft review before publication — every finding anchored and concrete, severities calibrated, sections and verdict wording conformant, no generic filler. Returns PASS or a defect list; never rewrites the review.
-tools: Read, Glob, Grep, mcp__gitnexus__context, mcp__gitnexus__query, mcp__gitnexus__list_repos
+tools: Read, mcp__gitnexus__context, mcp__gitnexus__query, mcp__gitnexus__list_repos
 maxTurns: 6
 ---
 

package/skills/gitnexus-review/ci-personas/ci-security-lens.md

@@ -1,7 +1,7 @@
 ---
 name: ci-security-lens
 description: CI review swarm lane. Audits a PR's changed trust boundaries — input handling, injection, unsafe parsing, secrets, workflow/config risk — with GitNexus taint and dependence evidence. Read-only; reports findings only.
-tools: Read, Glob, Grep, mcp__gitnexus__query, mcp__gitnexus__context, mcp__gitnexus__explain, mcp__gitnexus__pdg_query, mcp__gitnexus__impact, mcp__gitnexus__list_repos
+tools: Read, mcp__gitnexus__query, mcp__gitnexus__context, mcp__gitnexus__explain, mcp__gitnexus__pdg_query, mcp__gitnexus__impact, mcp__gitnexus__list_repos
 maxTurns: 12
 ---
 

package/skills/gitnexus-taint-analysis.md

@@ -148,13 +148,19 @@ finding is NOT proof of safety.
 
 ## Adding a source / sink / sanitizer
 
-Edit the language model in `taint/typescript-model.ts` (registered via the
-explicit `registerBuiltinTaintModels` seam, keyed by `SupportedLanguages`). The
-spec is hashable data (no functions). A sanitizer's `neutralizes` lists the
-EXACT sink kinds it defends — never a blanket kill. Add a fixture + assert the
-finding (or its absence) in `test/unit/taint/` (real-source harness:
-`test/helpers/ts-cfg-harness.ts`); the end-to-end proof is
-`test/integration/cfg/`.
+Taint models cover four `SupportedLanguages` ids across three files:
+TypeScript and JavaScript use `taint/typescript-model.ts`, Python uses
+`taint/python-model.ts`, and Java uses `taint/java-model.ts`. Edit the model
+for the language you are targeting. The explicit
+`registerBuiltinTaintModels` seam in `typescript-model.ts` registers all four;
+it is not an import side effect.
+
+The spec is hashable data (no functions). A sanitizer's `neutralizes` lists
+the EXACT sink kinds it defends — never a blanket kill. Add a fixture + assert
+the finding (or its absence) in `test/unit/taint/`. TypeScript and JavaScript
+use the real-source harness `test/helpers/ts-cfg-harness.ts`; Python and Java
+model matches are covered by `python-model-match.test.ts` and
+`java-model-match.test.ts`. The end-to-end proof is `test/integration/cfg/`.
 
 ## Validation checklist for any `--pdg` change
 

package/skills/gitnexus-work/SKILL.md

@@ -216,7 +216,10 @@ Work through plan §7 step by step, in order. For each step:
    `detect_changes` → commit as one unbroken sequence from the repository
    root — interleaving other work between the gate and the commit is how
    the gate gets skipped. Unexpected
-   affected flows → investigate before committing, not after.
+   affected flows → investigate before committing, not after. A result
+   flagged `partial` (a graph query failed) or `truncated` (the symbol
+   listing was capped) blocks the commit the same way: the gate did not
+   see every changed symbol, so re-run it rather than read it as clean.
 
 A relationship-affecting implementation edit or commit invalidates the
 procedure's prior proof. The next step must perform the required inter-step

package/skills/gitnexus-work/references/evidence-provenance.md

@@ -98,8 +98,11 @@ excluded.
 
 ## Safe existing-plan read contract
 
-`read-plan` fails closed unless Linux `/proc/self/fd`, `O_DIRECTORY`, and
-`O_NOFOLLOW` are available. It resolves the exact Git top-level, opens the
+`read-plan` fails closed unless the host platform can resolve names against a
+held directory descriptor: Linux `/proc/self/fd` with `O_DIRECTORY` and
+`O_NOFOLLOW`, or macOS `O_DIRECTORY`/`O_NOFOLLOW`. Every other platform is
+refused outright — an unverified read is not a degraded read, it is a different,
+racy operation. It resolves the exact Git top-level, opens the
 repository root and every plan parent as held no-follow directory descriptors,
 rejects missing, symlink, non-directory, and escaping parents, and opens the
 leaf with `O_NOFOLLOW`. It reads at most 16 MiB from that held file descriptor,
@@ -109,13 +112,17 @@ Neither Deepen nor work may parse bytes obtained before or outside this receipt.
 
 ## Safe generated-plan write contract
 
-The writer fails closed unless Linux `/proc/self/fd`, `O_DIRECTORY`,
-`O_NOFOLLOW`, and Python 3 with libc `renameat2(RENAME_NOREPLACE)` support are
-available. Python may live in `/usr/local`, a Nix profile, or another absolute
-PATH directory, but the helper accepts only a resolved executable and
-containing directory owned by root or the current user and not writable by
-group/other. The resolved executable is opened without following links and
-invoked through that held descriptor. Relative PATH entries are ignored. The plan parent and the
+The writer fails closed unless the host platform offers `O_DIRECTORY` and
+`O_NOFOLLOW`, plus `/proc/self/fd` on Linux. It spawns no interpreter and loads
+no native code: publication is `link(2)`, which is atomic, fails `EEXIST` when
+the destination name is taken, and refuses a symlinked destination without
+following it — the same no-replace guarantee `renameat2(RENAME_NOREPLACE)` and
+`renameatx_np(RENAME_EXCL)` provide, available through `fs.linkSync` on every
+supported platform. The temporary name is unlinked once the link succeeds; the
+published file is the same inode the writer created and verified, so every
+identity check downstream holds by construction. A link that succeeds followed
+by an unlink that fails leaves the plan published and is reported as success,
+because it is one. The plan parent and the
 repository's Git-admin directory must also share a filesystem. It resolves
 the target repository's exact Git top-level, opens that root and every
 destination parent as held no-follow directory descriptors, creates missing
@@ -128,15 +135,45 @@ The writer creates a random exclusive temporary file relative to the held final
 parent descriptor and keeps its no-follow descriptor open. It writes and
 flushes the bytes, binds the temporary name to the opened inode, and hashes the
 open file before publication. Immediately before publication it revalidates
-the parent and the temporary path, inode, size, and digest. Publication uses an
-atomic no-replace move relative to the held directory descriptor. Initial mode
-therefore cannot overwrite a destination that appears after the absent check.
+the parent and the temporary path, inode, size, and digest. Publication links
+the temporary name to the destination relative to the held directory
+descriptor, which fails rather than replaces if the destination is taken.
+Initial mode therefore cannot overwrite a destination that appears after the
+absent check.
 The writer then flushes the directory and revalidates the committed path by
 opening it with `O_NOFOLLOW`, hashing both the original temporary fd and the
 path-bound fd, and performing a second descriptor-anchored path identity check
 after hashing. A detected mutation or replacement aborts instead of accepting
 mixed-era output.
 
+### Linux anchors, macOS verifies
+
+The two platforms reach the same destination by different proofs, and the
+difference is real enough to state rather than smooth over.
+
+On Linux every name resolves through `/proc/self/fd/<fd>/<child>`, a magic link
+the kernel resolves against the inode the descriptor already holds. The names
+above it are never re-walked, so an attacker who renames a parent between the
+check and the use cannot redirect the operation. The race is impossible, not
+merely detected.
+
+macOS has no such path. `/dev/fd/<fd>` is a devfs node, not a magic link: it can
+be opened, but nothing can be resolved through it. `open("/dev/fd/<fd>/child")`
+returns `ENOENT`, and `realpath` of it returns `/dev/fd/<fd>` rather than the
+directory's path — measured on macOS 26, not inferred. Node exposes no `openat`,
+no `dir_fd` parameter, and no FFI, so on macOS the writer resolves names
+lexically with `O_NOFOLLOW` at every component, holds an open descriptor on
+every directory in the chain for the whole operation, and proves before *and*
+after each step that the chain still names exactly the inodes it is holding.
+Holding the descriptors is what makes the recorded inode numbers trustworthy:
+an open descriptor pins its inode, so a freed number cannot be recycled beneath
+the walk.
+
+What that buys is detection rather than prevention. A parent swapped inside the
+window between a check and its use is caught by the check that follows, and the
+operation aborts having written nothing — but on Linux it could not have
+happened at all. No published byte escapes verification on either platform.
+
 `--replace` accepts only a pre-existing regular file and is reserved for
 Deepen; without it, accidental overwrite is rejected. It also requires the
 exact canonical `generated_plan_path` and `plan_digest` from the same session's