gitnexus 1.6.10-rc.21 → 1.6.10-rc.211

package/skills/gitnexus-plan/references/context-ledger.md

@@ -0,0 +1,137 @@
+# Context ledger
+
+The ledger is gitnexus-plan's working memory. It exists to make repeated
+investigation impossible-by-discipline: **before every GitNexus call and
+every repo file read, check it.** Keep it as structured notes in your working
+context (or a scratchpad file _outside the repo_ for very long sessions); it
+is never published verbatim — the plan and context pack are distilled from
+it. This skill's own reference files are exempt from ledger bookkeeping.
+
+## Schema
+
+```yaml
+context_ledger:
+  task:
+    original_request: ''
+    interpreted_goal: ''
+    category: '' # Phase 0 classification
+    acceptance_criteria: []
+
+  verified_at_commit:
+    '' # target repo HEAD, recorded once in Phase 1;
+    # every line citation in the plan pins to it
+
+  evidence_provenance: {} # required immutable working snapshot; populate
+    # exactly from context-pack.md's normative schema
+
+  index_refresh:
+    '' # analyze --index-only runs: command + outcome
+    # (or "skipped: <reason>"). Budget is
+    # owned by SKILL.md Phase 1: one refresh plus
+    # at most one Phase 3 --pdg upgrade per session
+
+  established_facts: [] # each with its evidence source
+
+  symbols: # budgets count active (primary/related) only;
+    # discards are free — but on budget overflow,
+    # discard something before promoting
+    - name: ''
+      kind: ''
+      file: ''
+      relevance: 'primary | related | discarded'
+      source_verified: false # flipped in Phase 4; required before naming in Proposed Changes
+
+  files_read:
+    - file: ''
+      ranges: [] # e.g. ["120-188"]
+      purpose: ''
+
+  gitnexus_queries:
+    - query: '' # tool + args
+      purpose: '' # the planning question it answers
+      conclusion: '' # one line; details stay in working memory
+      key_output: '' # one-line raw quote when the plan leans on this result
+
+  pdg_slices:
+    - symbol: ''
+      purpose: ''
+      conclusion: ''
+
+  unresolved_questions: []
+  assumptions: [] # explicit, carried into plan §12
+  decisions: [] # with rationale, carried into plan §6/§7
+```
+
+## Evidence provenance
+
+`context-pack.md` is the sole normative emitted field schema, and
+`evidence-provenance.md` plus `../scripts/evidence-provenance.mjs` are the
+normative byte contract and implementation. Keep the helper's exact schema-2
+output in the ledger; do not redefine, abbreviate, or independently reproduce
+its canonicalization here.
+
+Build `evidence_provenance` immediately before composing the plan, after all
+source verification, by invoking the helper exactly as described in
+`evidence-provenance.md`. It is a versioned, canonical snapshot of both the
+whole working tree and every path that supports a plan citation:
+
+- `global_dirty_digest` is SHA-256 over the helper's versioned, NUL-framed
+  records for
+  **every dirty repo-relative path**, not only cited paths. Each record includes
+  path, state, object kind, every available layer digest, and both endpoints of
+  a rename. Overlapping porcelain facts for one path are merged; for example,
+  a staged deletion plus a recreated untracked file is `mixed` and retains
+  both its Git-backed and untracked layers. States are `staged`, `unstaged`,
+  `untracked`, `deleted`, `renamed`, or `mixed`. Exclude only this run's
+  normalized repo-relative generated plan path so writing the plan cannot
+  invalidate its own evidence; do not exclude the rest of `docs/plans/`.
+- `cited_path_manifest` is sorted by normalized repo-relative path and
+  includes every path cited by a `[verified]` claim or named as evidence in
+  the context pack. Record clean paths too. A path entry has this shape:
+
+```yaml
+- path: 'src/example.ts'
+  object_kind: # each layer: regular | symlink | gitlink | directory | absent
+    head: 'regular'
+    index: 'regular'
+    worktree: 'regular'
+    untracked: 'absent'
+  state: 'clean | staged | unstaged | untracked | deleted | renamed | mixed | absent'
+  rename_from: null
+  rename_to: null
+  head_digest: 'sha256:<hex> | absent'
+  index_digest: 'sha256:<hex> | absent'
+  worktree_digest: 'sha256:<hex> | absent'
+  untracked_digest: 'sha256:<hex> | absent'
+```
+
+Use Git object contents for HEAD and index digests and filesystem bytes for
+worktree/untracked digests; never confuse an absent layer with an empty file.
+Hash symlink targets as link text and gitlinks as object IDs. If a cited path
+cannot be classified or read, the plan must mark the evidence unavailable
+instead of emitting a digest it did not prove.
+
+## Reread rules
+
+Do **not** repeat a query or reread a source range unless one of:
+
+- the previous result was incomplete for the question at hand;
+- the source is known to have changed (an edit happened);
+- validation exposed a contradiction between graph and source.
+
+**Allowed repeats** (deliberate escalations, not violations):
+
+- `summaryOnly: true` → full drill-down on the same `impact` target;
+- an `ambiguous` result retried once with `kind` / `file_path` / uid narrowing;
+- the same tool re-run with a changed parameter that answers a _new_ planning
+  question (e.g. `pdg_query` `controls` then `flows` on one function).
+
+When a repeat is justified, note in the ledger _why_ the earlier entry was
+insufficient. A ledger full of near-duplicate queries is the failure signal —
+stop and plan with what is established.
+
+## Discarding
+
+Symbols and queries that turned out irrelevant stay in the ledger marked
+`discarded` with a one-line reason. That is what prevents re-walking dead
+ends later in the session.

package/skills/gitnexus-plan/references/context-pack.md

@@ -0,0 +1,126 @@
+# Implementation context pack
+
+Section 11 of the plan. The stable, machine-readable contract a follow-up
+implementation agent (`gitnexus-work`, or any executor) consumes to start
+work **without repeating the investigation**. Distilled from the ledger;
+every entry traceable to verified evidence.
+
+**Compact plans emit the mini-pack** — only: `task_summary`,
+`evidence_provenance`, `files_to_modify`, `tests`,
+`verification_commands`, `pdg_constraints` (only when a slice actually
+ran), `assumptions`, `open_questions`, `avoid`. Full plans emit every
+field. Field semantics are identical in both; `evidence_provenance` is
+mandatory in both forms. `gitnexus-work` treats absent optional fields as
+empty, not as errors.
+
+## Schema
+
+This is the sole normative emitted `evidence_provenance` field schema. The
+portable byte contract and executable serializer live in
+`evidence-provenance.md` and `../scripts/evidence-provenance.mjs`; sibling
+documents must reference them rather than reimplementing canonical bytes.
+
+```yaml
+implementation_context:
+  task_summary: ''
+  acceptance_criteria: []
+
+  evidence_provenance:
+    schema_version: 2
+    head_commit: '' # full commit SHA that source citations pin to
+    # normalized repo-relative docs/plans/<date>-gitnexus-plan-<3-5-word-slug>.md;
+    # safely written; exact path excluded from global_dirty_digest
+    generated_plan_path: ''
+    global_dirty_digest:
+      algorithm: 'sha256'
+      canonicalization: 'gitnexus-evidence-provenance-v2 NUL-framed UTF-8 records'
+      value: '' # digest only; do not embed the whole dirty-path manifest
+    cited_path_manifest: # sorted by normalized repo-relative path
+      - path: ''
+        object_kind: # per layer: regular | symlink | gitlink | directory | absent
+          head: ''
+          index: ''
+          worktree: ''
+          untracked: ''
+        state: 'clean | staged | unstaged | untracked | deleted | renamed | mixed | absent'
+        rename_from: null
+        rename_to: null
+        head_digest: 'sha256:<hex> | absent'
+        index_digest: 'sha256:<hex> | absent'
+        worktree_digest: 'sha256:<hex> | absent'
+        untracked_digest: 'sha256:<hex> | absent'
+
+  primary_symbols:
+    - symbol: ''
+      file: ''
+      lines: ''
+      role: ''
+
+  related_symbols:
+    - symbol: ''
+      relationship: '' # CALLS / IMPORTS / EXTENDS / test-of / ...
+      relevance: ''
+
+  execution_path: [] # ordered prose steps, from §2/§5
+
+  pdg_constraints: # from the PDG slice; empty + note if no layer
+    - description: ''
+      affected_statements: [] # "<file>:<line>" refs
+      implementation_consequence: ''
+
+  architectural_patterns:
+    - pattern: ''
+      example_location: '' # repo-relative file (+ symbol)
+      usage_guidance: ''
+
+  files_to_modify:
+    - file: ''
+      symbols: []
+      intended_change: ''
+
+  tests:
+    - file: '' # existing file to update, or new path to create
+      scenarios: [] # input → action → expected outcome
+
+  verification_commands: [] # real commands verified to exist AND be runnable —
+    # prefer npm/CI scripts that carry their pre-hooks
+
+  risks: []
+  assumptions: [] # faithful condensation of plan §12 assumptions;
+    # each entry names WHAT to check and HOW —
+    # gitnexus-work re-verifies them before executing
+  open_questions: [] # faithful condensation of plan §12 open questions
+
+  avoid:
+    - 'Do not repeat full repository discovery'
+    - 'Do not replace established patterns without evidence'
+    # + task-specific prohibitions discovered during planning
+```
+
+## Must not contain
+
+- full files;
+- the repository-wide raw dirty-path manifest (store only its canonical
+  `global_dirty_digest`; detailed entries are bounded to cited paths);
+- large raw GitNexus responses;
+- unfiltered PDG dumps;
+- duplicate code excerpts (cite `file:line`, don't re-quote);
+- speculative implementation details presented as facts.
+
+## Stability contract
+
+Field names above are the interface consumed by `gitnexus-work` (fields it
+does not act on directly travel as executor context). Add fields
+freely; do not rename or repurpose existing ones. `assumptions` and `avoid`
+are load-bearing: an executor treats `assumptions` as things to re-verify
+cheaply before relying on them, and `avoid` as hard constraints.
+`evidence_provenance` is also load-bearing: its version, global digest, and
+sorted cited-path manifest let the executor distinguish commit drift from
+staged, unstaged, untracked, deleted, renamed, mixed, or absent working-tree
+evidence. Legacy packs that lack it or use schema 1 require a conservative
+schema-2 re-anchor; they are not interpreted as a clean tree.
+`generated_plan_path` is always normalized, relative to the target repo, and
+scoped to the generated-plan filename shape under `docs/plans/`; schema 2 has
+no external-output representation. An executor must load the plan with the
+helper's descriptor-anchored `read-plan` command and require this field to
+equal the receipt's canonical target-repo-relative path byte-for-byte.

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

@@ -0,0 +1,309 @@
+# Evidence provenance serializer v2 and safe plan writer
+
+This file is the normative byte contract for `evidence_provenance` schema 2.
+The adjacent `scripts/evidence-provenance.mjs` is its executable definition.
+`gitnexus-plan` and `gitnexus-work` carry byte-identical copies so either skill
+can produce the same snapshot without relying on the other skill's install.
+It is also the only supported write boundary for a generated plan. Never
+recreate the digest with an ad-hoc shell pipeline or write the plan destination
+directly.
+
+## Invocation
+
+From the target repository root, run the helper belonging to the active skill:
+
+```bash
+node <skill-dir>/scripts/evidence-provenance.mjs read-plan \
+  --repo "$PWD" \
+  --generated-plan docs/plans/YYYY-MM-DD-gitnexus-plan-example-change-plan.md
+```
+
+`read-plan` is the only supported way to load an existing plan for Deepen or
+execution. It emits a JSON receipt with the canonical `generated_plan_path`,
+`bytes_read`, exact `plan_bytes_base64`, and `plan_digest` (`sha256:<hex>`).
+Decode and consume those exact bytes; do not reopen the lexical path. Retain
+the canonical path and digest together for the complete Deepen session; a
+receipt for one path never authorizes another, even when their bytes match.
+
+```bash
+node <skill-dir>/scripts/evidence-provenance.mjs snapshot \
+  --repo "$PWD" \
+  --schema-version 2 \
+  --generated-plan docs/plans/YYYY-MM-DD-gitnexus-plan-example-change-plan.md \
+  --cited src/one.ts \
+  --cited test/one.test.ts
+```
+
+Pass one `--cited` argument for every cited path. The helper emits the complete
+JSON value for `evidence_provenance`; copy that value without rewriting fields.
+`gitnexus-work` passes the plan's `schema_version`, `generated_plan_path`, and
+every path in `cited_path_manifest`. Schema 1 is legacy and deliberately
+rejected, so the executor must conservatively re-anchor it under schema 2.
+
+After the snapshot is in the fully composed document, publish its exact UTF-8
+bytes through the same helper:
+
+```bash
+node <skill-dir>/scripts/evidence-provenance.mjs write-plan \
+  --repo "$PWD" \
+  --generated-plan docs/plans/YYYY-MM-DD-gitnexus-plan-example-change-plan.md \
+  < /path/to/outside-repo-scratch-plan.md
+```
+
+For Deepen only:
+
+```bash
+node <skill-dir>/scripts/evidence-provenance.mjs write-plan \
+  --repo "$PWD" \
+  --generated-plan docs/plans/YYYY-MM-DD-gitnexus-plan-example-change-plan.md \
+  --replace \
+  --expected-plan-path docs/plans/YYYY-MM-DD-gitnexus-plan-example-change-plan.md \
+  --expected-plan-digest 'sha256:<digest-from-read-plan>' \
+  < /path/to/outside-repo-scratch-plan.md
+```
+
+Initial planning never passes `--replace`; an existing destination is an
+error. Deepen mode rewrites the same path by adding `--replace`,
+`--expected-plan-path <generated_plan_path-from-read-plan>`, and
+`--expected-plan-digest <plan_digest-from-that-same-receipt>`. Standard input must be
+valid UTF-8 and at most 16 MiB. A successful write prints a JSON receipt with
+the normalized `generated_plan_path` and `bytes_written`. A successful Deepen
+write also returns `prior_plan_backup_git_path`, a durable Git-admin path for
+the displaced plan. The CLI rejects every option that does not apply to its
+selected command; the direct API likewise requires literal booleans and exact
+digest strings rather than truthy coercion.
+
+## Path contract
+
+Every Git path and CLI path must be valid UTF-8, already normalized to Unicode
+NFC, and a nonempty POSIX repo-relative path. NUL, backslash, absolute/drive
+paths, empty components, and `.` or `..` components are rejected. The helper
+does not silently repair or alias them. Invalid UTF-8 from Git, non-NFC names,
+unmerged index stages, unsupported Git modes, sockets/devices/FIFOs, unreadable
+objects, symlink traversal in a parent path component, or a repository mutation
+observed during the snapshot fail closed.
+
+The generated-plan path is always repo-relative under schema 2. Snapshot
+exclusion and writing require exactly
+`docs/plans/YYYY-MM-DD-gitnexus-plan-<3-5-word-kebab-slug>.md`, including a
+valid calendar date; they cannot target `.git`, source, configuration, or an
+arbitrary repo file. For compatibility with documented and legacy plans,
+`read-plan` accepts normalized files matching `docs/plans/*gitnexus-plan*.md`,
+while retaining the same descriptor-anchored containment checks. That read
+compatibility does not widen the writer. External output has no schema-2
+representation. The snapshot exclusion is one exact normalized path
+comparison. No glob, directory, basename, or `docs/plans/`-wide exclusion is
+permitted. If the exact path is a rename endpoint, only that endpoint record is
+excluded.
+
+## Safe existing-plan read contract
+
+`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,
+requires valid UTF-8, hashes the exact bytes, then proves both the parent chain
+and lexical leaf still name the same held objects before returning its receipt.
+Neither Deepen nor work may parse bytes obtained before or outside this receipt.
+
+## Safe generated-plan write contract
+
+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
+parents relative to those descriptors, and proves the descriptor and lexical
+chains still identify the same directories at the write boundary. A symlink
+or non-directory parent, an escaping resolved path, a symlink/non-regular final
+target, or a parent swap is an error.
+
+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 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
+`read-plan` receipt. The expected path must exactly equal the write
+destination, so identical bytes from one plan cannot authorize another plan.
+Immediately before
+preservation, the writer hashes the still-held prior-plan fd and rejects any
+digest, inode, or path mismatch, including same-inode edits and changes between
+read and write. It then atomically moves the current destination without
+replacement to a random `gitnexus-plan-backups/` file under the resolved
+Git-admin directory and verifies the moved inode and digest against that held
+fd. Only then does it publish the new plan with the same atomic no-replace
+primitive. A destination that reappears at either boundary is left untouched.
+
+Every newly created plan or vault directory is fsynced and then fsynced into
+its containing directory. Every cross-directory preservation move fsyncs both
+its source and destination directories before success or a recovery path is
+reported. After temporary bytes exist, a failed publication or verification preserves
+every available prior, displaced, unpublished, or intended plan in that
+Git-admin vault before reporting failure. Each reported recovery is reopened
+from a freshly resolved Git root and verified before the error names it as
+`git-path:gitnexus-plan-backups/<random-name>`. Resolve that value with
+`git rev-parse --git-path gitnexus-plan-backups/<random-name>`; never interpret
+it as a repo-relative working-tree path. This remains valid if the held plan
+parent was renamed after publication. The writer never reports recovery
+through a stale lexical parent and never performs an identity-check-then-unlink
+rollback that could delete a racer's replacement. Read-only or unsupported
+checkouts produce a blocking error. Callers must not bypass the helper,
+redirect to an external path, or weaken these checks.
+
+## Canonical bytes
+
+The `global_dirty_digest.value` is lowercase SHA-256 (without a `sha256:`
+prefix) over this byte stream. All textual values are their exact UTF-8 bytes.
+`NUL` below is one `0x00` byte.
+
+1. Prefix fields, each followed by NUL, then one additional NUL:
+   `gitnexus-evidence-provenance`, `schema_version`, `2`.
+2. Zero or more records sorted by unsigned lexicographic comparison of the
+   normalized path's UTF-8 bytes. Locale and filesystem order are forbidden.
+3. Each record is `record` + NUL, then the following fixed-order sequence of
+   `field-name` + NUL + `field-value` + NUL pairs, then one additional NUL:
+   `path`, `state`, `head_kind`, `index_kind`, `worktree_kind`,
+   `untracked_kind`, `rename_from`, `rename_to`, `head_digest`,
+   `index_digest`, `worktree_digest`, `untracked_digest`.
+4. The literal `absent` represents every unavailable rename endpoint, object
+   kind, and layer digest in canonical bytes. It is never an empty string.
+
+The schema's canonicalization literal is exactly
+`gitnexus-evidence-provenance-v2 NUL-framed UTF-8 records`. The fixed field
+count plus the extra NUL after prefix/record makes framing unambiguous; values
+cannot contain NUL. Duplicate normalized paths are rejected.
+
+## Records, renames, and states
+
+The raw dirty set comes from Git porcelain v2 with NUL termination, all
+untracked files, submodule inspection enabled, a fixed 50% rename threshold,
+and both `diff.renameLimit=0` and `status.renameLimit=0`, so repository config
+cannot cap rename candidates. Raw porcelain facts that share a path are merged
+into one canonical record. A rename contributes two endpoint facts:
+
+- old endpoint: `path=<old>`, `rename_from=absent`, `rename_to=<new>`;
+- new endpoint: `path=<new>`, `rename_from=<old>`, `rename_to=absent`.
+
+Both normally have state `renamed`; record sorting, not old/new role,
+determines order. A worktree-dirty rename destination or any endpoint that also
+has another fact is `mixed`, with rename metadata retained. When either endpoint
+is cited, the cited manifest expands to include both.
+
+Ordinary `XY` status maps to `mixed` when index and worktree columns are both
+dirty, otherwise `deleted` for a deletion, `staged` for index-only change, and
+`unstaged` for worktree-only change. `?` is `untracked`. Multiple distinct
+facts for the same path become `mixed`; a staged deletion plus a recreated file
+therefore retains HEAD/index facts while the filesystem object is recorded in
+the untracked layer. `? child/` is Git's embedded-directory marker: the trailing
+slash is removed before path normalization and `child` is materialized as one
+bounded directory object. A cited path outside the dirty set is `clean`,
+`untracked` when it exists only outside Git layers, or `absent` when no layer
+exists.
+
+## Object and digest rules
+
+Every present layer digest is `sha256:<lowercase-hex>`:
+
+- HEAD regular/symlink: SHA-256 of the exact Git blob bytes. HEAD directory:
+  SHA-256 of the exact raw Git tree bytes. HEAD gitlink: SHA-256 of the ASCII
+  object ID stored by the tree.
+- Index regular/symlink: SHA-256 of the stage-0 Git blob bytes. Index gitlink:
+  SHA-256 of its ASCII object ID. The index has no directory layer. Any
+  non-stage-0 entry is rejected.
+- Tracked worktree regular: raw file bytes, opened without following symlinks.
+  Symlink: raw link-target bytes. Gitlink: ASCII object ID at the checked-out
+  nested HEAD, but only after `rev-parse --show-toplevel` proves that the
+  directory itself is the nested repository root, `HEAD` resolves there, and
+  porcelain v2 reports no staged, unstaged, untracked, or ignored nested changes. The
+  same root, HEAD, and clean-status proof is repeated by the mutation guard. A
+  dirty, empty, uninitialized, or parent-falling-through gitlink fails closed.
+  Directory: the v1 directory stream described below.
+- A path absent from both HEAD and index places the filesystem object in the
+  `untracked` layer and marks `worktree` absent. A Git-backed path places it in
+  `worktree` and marks `untracked` absent. A missing layer uses literal
+  `absent` for both kind and digest; an empty file is the SHA-256 of zero bytes.
+
+Filesystem directory bytes use prefix fields
+`gitnexus-evidence-directory`, `schema_version`, `1`, the same NUL framing,
+and recursive entries sorted by unsigned UTF-8 relative-path bytes. Each entry
+has fixed fields `path`, `kind`, `digest`. A single bottom-up filesystem walk
+visits each node once and returns each child digest plus the flattened subtree
+needed to preserve those canonical bytes; links are never followed. When the
+directory is proven to be an exact nested Git top-level, only its administrative
+`.git` entry is excluded. Every other child, including working files and nested
+directories, remains evidence.
+
+Each directory object is bounded to 10,000 visited entries, depth 256, and 256
+MiB of regular-file content. Exceeding a bound fails closed. These bounds apply
+independently to each top-level directory object materialized by a record.
+
+HEAD objects are read only from the full object ID captured at snapshot start;
+the symbolic `HEAD` name is never re-resolved for layers. Index layers are
+parsed from one captured stage-0 listing. The helper guards the corresponding
+HEAD/ref/reflog controls and raw index file, compares the captured listing at
+the end, and rejects ordinary A-to-B-to-A mutations instead of accepting
+mixed-era layers.
+
+Regular files are read through an `O_NOFOLLOW` descriptor with before/after
+identity checks. Symlinks use lstat/readlink/lstat; directories record identity
+before and after their inventory. The helper also compares raw porcelain-v2
+status and HEAD at the start and end, then rechecks filesystem guards. An
+absent cited path holds a no-follow descriptor for the nearest existing parent
+and records the first missing component or leaf; that anchored absence is
+checked both before and after the final Git status pass, so a newly created
+ignored path cannot evade porcelain. Any observed race rejects the snapshot
+rather than emitting mixed-era evidence.