gitnexus 1.6.9 → 1.6.10-aptos.1

package/skills/gitnexus-work/SKILL.md

@@ -0,0 +1,269 @@
+---
+name: gitnexus-work
+description: 'Use when executing an engineering plan produced by gitnexus-plan (or a small bounded task directly) — implements step by step with GitNexus impact checks before every symbol edit, tests from the plan''s scenarios, and detect_changes gating every commit. Examples: "/gitnexus-work docs/plans/2026-07-11-gitnexus-plan-ingestion-retry.md", "/gitnexus-work" (latest plan), "execute the plan".'
+---
+
+# gitnexus-work — execute a gitnexus-plan
+
+Execute an implementation plan produced by `gitnexus-plan`, shipping it as a
+sequence of verified, atomic commits. The plan's section 11
+(`implementation_context` pack) is the primary machine-readable input; the
+prose sections are its rationale. This skill **does** edit code — it is the
+executor counterpart to the planning-only `gitnexus-plan`.
+
+```
+/gitnexus-work <plan path>        # execute this plan
+/gitnexus-work                    # newest docs/plans/*gitnexus-plan*.md here
+/gitnexus-work <small task text>  # direct mode, see Input triage
+```
+
+## Input triage
+
+- **Plan path** (or blank → the newest `docs/plans/*gitnexus-plan*.md` under
+  the current repo root): the normal mode; continue to Phase 1. Schema-2
+  plans have a normalized repo-relative
+  `docs/plans/YYYY-MM-DD-gitnexus-plan-<3-5-word-slug>.md`
+  `generated_plan_path`. Resolve only a lexical candidate, then invoke
+  `scripts/evidence-provenance.mjs read-plan --repo <root> --generated-plan
+<candidate>` and load only the exact bytes in its descriptor-anchored
+  receipt. Require the receipt's canonical repo-relative path to equal the
+  document's `generated_plan_path` byte-for-byte;
+  reject an external, escaping, differently scoped, or mismatched value. A
+  plan in another target repo may still be passed by explicit path. If Phase 1's
+  pre-completed check finds every §7 step of the newest plan already landed,
+  stop and ask instead of re-executing it.
+- **Bare task text**: trivial and bounded (1–2 files, no architectural
+  decisions) → implement directly with the same discipline: `impact` before
+  every symbol edit, minimal change, tests when behavior changes,
+  verification commands taken from the repo's own scripts (package.json /
+  CI), `detect_changes` before every commit, and the shared
+  Build-current/index-current procedure before graph-dependent impact and
+  final verification. Anything larger → recommend running
+  `/gitnexus-plan` first; honor the user's choice if they decline.
+
+## Phase 1 — Load and re-anchor the plan
+
+1. Resolve the target repo and normalized plan candidate, then invoke this
+   skill's descriptor-anchored `scripts/evidence-provenance.mjs read-plan`
+   command exactly as
+   specified in `references/evidence-provenance.md`. Reject a missing,
+   external, escaping, symlinked, or differently scoped path. Decode and read
+   the receipt's exact `plan_bytes_base64` completely; never read or reopen the
+   lexical path directly. It is a decision artifact, not a script: scope
+   boundaries and `avoid` entries bind you; exact code is yours to write.
+   Retain the receipt's canonical `generated_plan_path` and `plan_digest` in
+   session state. Never edit the plan body.
+2. Parse the §11 `implementation_context` pack: `acceptance_criteria`,
+   `evidence_provenance`, `primary_symbols`, `related_symbols`,
+   `files_to_modify`, `execution_path`, `pdg_constraints`,
+   `architectural_patterns`, `tests`, `verification_commands`, `risks`,
+   `assumptions`, `open_questions`, `avoid`. Compact plans carry the
+   mini-pack subset — absent optional fields are empty, not errors.
+   `evidence_provenance` is mandatory: absence or schema 1 means a legacy
+   plan, not a clean tree. Before relying on it, require exact byte-for-byte
+   equality between the read-plan receipt's canonical `generated_plan_path`
+   and `evidence_provenance.generated_plan_path`.
+3. **Two-layer drift check — always recompute.** Even when current HEAD is the
+   same HEAD as the plan pin, recompute both the canonical global dirty digest
+   and the sorted cited-path manifest. Read
+   `references/evidence-provenance.md`, then invoke this skill's
+   `scripts/evidence-provenance.mjs` with the plan's exact
+   `generated_plan_path`, every cited manifest path, and schema version 2.
+   Never recreate its bytes in shell or prose. Schema 1 cannot be recomputed
+   unambiguously and requires conservative re-anchoring. Include
+   object kind plus HEAD/index/worktree/untracked layer digests, and classify
+   `staged`, `unstaged`, `untracked`, `deleted`, `renamed`, `mixed`,
+   and `absent` evidence. Honor the generated-plan exclusion exactly; do not
+   exclude all plans.
+4. **Re-anchor on either mismatch.** Missing or legacy provenance, a HEAD
+   mismatch, or a global dirty digest mismatch requires a conservative
+   re-anchor before work:
+   - Diff every cited-path manifest entry. Changed cited paths — including
+     staged-only, unstaged-only, deleted, both rename endpoints, mixed
+     staged+unstaged, and disappeared untracked paths — get their cited ranges
+     re-read before reliance.
+   - Compare the current whole-tree dirty set with the pinned global digest.
+     New uncited dirty paths get a scope assessment: determine whether they
+     overlap the plan, requirements, tests, or a key technical decision; do not
+     silently ignore them merely because they are uncited.
+   - Unreadable or unclassifiable cited evidence blocks every dependent step
+     until it can be restored, read, or resolved with the user. Never substitute
+     an invented digest or treat absence as an empty file.
+   - Keep the re-anchor result in session state; never mutate the plan body.
+     Use Deepen only if reconciliation invalidates scope, requirements, a key
+     technical decision (KTD), or the planned implementation seam. Ordinary
+     byte drift that leaves those decisions valid is re-verified locally.
+5. **Re-verify `assumptions` cheaply** (each one names what to check).
+   A failed assumption is a stop-and-replan signal for the steps that
+   depend on it, not something to code around silently.
+6. Note `open_questions` — if one blocks a step and the answer materially
+   changes the work, ask the user before that step, not after.
+7. **Pre-completed check.** If commits for this plan already exist on the
+   branch (a prior partial run, or a post-route-back Deepen cycle), verify
+   which §7 steps have landed at HEAD: those are skipped and reported as
+   pre-completed, and execution resumes at the first unlanded step. All
+   steps landed → report that and stop.
+
+## Phase 2 — Environment
+
+- On the default branch → create a feature branch named from the plan slug.
+  On a feature branch already → stay only if it is meaningful _for this
+  plan_ (name matches the plan slug, or the user confirms); otherwise
+  branch from here with the slug name.
+- If the plan document is not yet committed, commit it now
+  (`docs(plans): add <slug> plan`) — the plan travels with the work it
+  drives, and the final review diff then includes it.
+- Confirm the `verification_commands` from the pack actually run in this
+  checkout (dependencies installed, builds present) before starting, not
+  after the last step.
+
+### Build-current/index-current procedure
+
+This is the single graph-freshness procedure owned by `gitnexus-work`; it
+applies in plan mode and direct mode. Before every graph-dependent `impact`
+query, run the Build-current/index-current procedure. Before final graph
+verification, run the same Build-current/index-current procedure again.
+
+1. Capture current HEAD and working-tree provenance. Read
+   `gitnexus://repo/<name>/context` and use its typed `index.commit` and
+   `index.runner_identity` receipt — never infer analyzer identity from prose,
+   timestamps, or a path alone. Compare `index.commit` with current HEAD. A
+   current receipt has `schemaVersion: 4`, resolved runtime path/version, CLI
+   version, invoked-artifact path/digest, build
+   kind/root/canonicalization/digest, and dependency-runtime
+   manifest/lockfile/canonicalization/package-count/artifact-count/digest. Its
+   dependency canonicalization is
+   `gitnexus-analyzer-dependency-runtime-v4`. The dependency-runtime digest
+   covers resolved package metadata and complete loadable package payloads,
+   including JavaScript, JSON, native, Wasm, and parser artifacts; schema-1,
+   schema-2, and schema-3 receipts are legacy/stale (the MCP context labels
+   them `runner_identity_schema_status: legacy-or-unknown`). Require MCP
+   `index.incomplete_reasons: []`. Run the exact candidate CLI's
+   `status --json` command and require `index.runnerIdentityStatus: current`,
+   `index.incompleteReasons: []`, and top-level `status: up-to-date`. The
+   status comparator checks every semantic field while deliberately excluding
+   only diagnostic `invokedArtifact`; a worker-authored persisted receipt and
+   the CLI's live receipt may therefore differ in that field without becoming
+   stale. Missing, malformed, differently versioned, semantically unequal, or
+   incomplete receipts are unknown/stale, not a match.
+2. Relationship-affecting committed and uncommitted edits invalidate
+   freshness after the last successful procedure run. This includes staged,
+   unstaged, untracked, deleted, or renamed analyzer/source/config changes
+   that can alter symbols or edges. Any such edit between steps requires an
+   inter-step refresh before the next graph query, even when HEAD did not move.
+3. If the typed runner receipt is stale or unknown in an analyzer-source
+   checkout, build current local source using the verified package script. In
+   this repo: `cd gitnexus && npm run build`. Resolve the package's `bin`
+   target and run that exact artifact's `status --json` command to capture its
+   current receipt. Source/build timestamps are a conservative rebuild
+   trigger, not proof that an artifact is current.
+4. Invoke that exact freshly built local CLI from the target repo root with
+   PDG layers enabled. In this repo:
+   `node gitnexus/dist/cli/index.js analyze --index-only --pdg`.
+   Add `--force` when the persisted receipt was absent, malformed,
+   differently versioned, or unequal so an already-up-to-date fast path cannot
+   leave legacy/stale provenance in place. The usual project-runner form,
+   `node .gitnexus/run.cjs analyze`, is acceptable only when its proven runner
+   identity resolves to that same freshly built artifact. Do not fall back to
+   an older project runner, global install, or package download after
+   resolving/building the local artifact.
+5. Re-read index context, rerun the exact invoked CLI's `status --json`, and
+   prove the post-refresh `index.commit` equals current HEAD, MCP
+   `index.incomplete_reasons` is empty, and its complete
+   `index.runner_identity` equals status `index.runnerIdentity` (the persisted
+   receipt). Require status `index.runnerIdentityStatus: current`, empty
+   `index.incompleteReasons`, and top-level `status: up-to-date`; do not require
+   raw equality with `current.runnerIdentity` because `invokedArtifact` is a
+   diagnostic entrypoint deliberately excluded from semantic freshness.
+   Record the dirty-state digest indexed in this procedure so same-HEAD
+   uncommitted edits can invalidate it later.
+6. Any build, refresh, metadata-read, or identity-verification failure blocks
+   graph-dependent impact work and final completion. Report the failing
+   command and evidence; do not continue on an older graph.
+
+## Phase 3 — Execute the Implementation Sequence
+
+Work through plan §7 step by step, in order. For each step:
+
+1. **Fresh impact before editing.** Run the Build-current/index-current
+   procedure immediately before every graph-dependent
+   `impact {target, direction: "upstream"}` query. Then account for every
+   direct (d=1) dependent. HIGH or CRITICAL risk → surface it to the user
+   with the blast radius before proceeding (repo mandate — see AGENTS.md
+   GitNexus rules).
+2. **Honor the constraints.** `pdg_constraints` entries state ordering and
+   dependence facts the change must preserve; `avoid` entries are hard
+   prohibitions; `architectural_patterns` name the shape to mirror (read the
+   example location before inventing one).
+3. **Implement minimally.** The smallest change that completes the step,
+   following the surrounding code's conventions.
+4. **Test from the plan's scenarios.** Each `tests[]` scenario (input →
+   action → expected outcome) becomes a real test in the named file. Add
+   coverage the plan missed if the step's behavior demands it; never delete
+   or weaken an assertion to make a step pass. Prove a new regression test
+   discriminates: when the failure mode is subtle, run it once against the
+   pre-fix tree (write the test before the fix, or stash the fix) and watch
+   it fail — a test that passes both ways pins nothing.
+5. **Verify.** Run the step-relevant `verification_commands` (they carry
+   their build prerequisites; use them as written). If any part of the
+   change executes from build output — worker entrypoints, dist-shipped
+   CLIs, bundled assets — rebuild that output before every verification
+   run: a pass or fail against outdated build output is noise, and "the
+   fix doesn't work" is more often "the fix never loaded".
+6. **Commit atomically.** `detect_changes {scope: "staged"}` before every
+   commit to confirm only the expected symbols and flows are affected
+   (repo mandate); then one conventional commit per step. Run stage →
+   `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.
+
+A relationship-affecting implementation edit or commit invalidates the
+procedure's prior proof. The next step must perform the required inter-step
+refresh before its impact query; final verification refreshes again after the
+last edit.
+
+Steps are independently actionable: after any commit the tree is coherent.
+If a step reveals the plan is wrong, stop that step, re-verify the affected
+claims at HEAD, and either adapt (small, in-scope deviation — record it in
+the commit message and final summary) or route back to `gitnexus-plan`
+Deepen mode (structural miss) — with a one-line ask to the user when the
+choice isn't obvious.
+
+## Phase 4 — Finish
+
+1. Run the full `verification_commands` suite once, at the end, even if
+   every step already passed individually.
+2. Walk plan §13 (Definition of Done) and the pack's `acceptance_criteria`
+   item by item; anything unmet is either finished now or reported as
+   explicitly unmet — never silently dropped.
+3. **Verify the final knowledge graph.** Before final graph verification, run
+   the same Build-current/index-current procedure after the last edit, even
+   when no commit landed or HEAD still equals the original pin. Then run
+   `detect_changes {scope: "all"}` (or the repo's equivalent final graph
+   check) against that proven-current index and account for every unexpected
+   symbol or flow. A procedure failure blocks completion.
+4. Report: steps completed, commits made, deviations from the plan (with
+   why), assumptions that failed re-verification, DoD status, final indexed
+   commit and runner identity, and anything deferred. Test failures are
+   reported with their output, not smoothed over.
+
+## Never
+
+- Skip the Phase 3 gates: no symbol edit without `impact`, no commit without
+  `detect_changes`.
+- Expand scope beyond the plan — §12's deferred follow-ups stay deferred.
+- Mutate the plan body (committing the file verbatim in Phase 2 is not
+  mutation), weaken failing tests, or present unverified work as verified.
+
+## Skill feedback (GitNexus repo only)
+
+If this run exposed friction in this skill's own instructions — wrong or
+missing guidance, a wasted tool budget, a phase that misrouted — and the repo
+carries `eval/workflow_bench/`, append one JSON line to
+`eval/workflow_bench/learnings.jsonl` (create the file if absent):
+`{"skill": "gitnexus-work", "date": "YYYY-MM-DD", "task": "<one line>", "friction": "<one line>", "suggestion": "<one line>"}`.
+Never edit this skill file itself from a live task: improvements go through
+the offline candidate loop (`eval/workflow_bench/README.md` § Prompt and
+skill evolution loop), where a candidate must beat the incumbent on the
+paired benchmark before a human merges it.

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

@@ -0,0 +1,272 @@
+# 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 Linux `/proc/self/fd`, `O_DIRECTORY`, and
+`O_NOFOLLOW` are available. 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 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
+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 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 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.
+
+`--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.