feat(directives): scavenge from nagent_review_20260608/: 5 directives

This commit is contained in:
ed
2026-07-04 00:13:24 -04:00
parent bea5d6b151
commit ebca201d39
10 changed files with 174 additions and 0 deletions
@@ -0,0 +1,9 @@
# file_id_stable_across_rename
## v1
**Why this iteration:** Lifted from `conductor/tracks/nagent_review_20260608/nagent_takeaways_20260608.md:128-130` (Pattern 4 — "File-identity over file-path — a stable st_dev:st_ino is rename-safe"). The nagent primitive is `file_id_for_path(path) -> "{st_dev}:{st_ino}"`; the same primitive applies to Manual Slop's `FileItem` and any per-file durable cache.
**Source:** `conductor/tracks/nagent_review_20260608/nagent_takeaways_20260608.md:128-130`
---
**Lifted:** 2026-07-02 (scavenge pass — directive library expansion from nagent_review track)
@@ -0,0 +1,26 @@
# Durable per-file memory is keyed by file_id (st_dev:st_ino), not by path — renames preserve identity
## The identity primitive
When memory is attached to a specific file on disk (a per-file conversation, a curation snapshot, a summary cache), the lookup key is the file's inode pair `{st_dev}:{st_ino}`, not the path string.
Per `conductor/tracks/nagent_review_20260608/nagent_takeaways_20260608.md:128-130`: "nagent_file_edit_lib.py:file_id_for_path(path) -> '{st_dev}:{st_ino}'. The per-file conversation index keys by inode, not by path. Rename the file in place (same inode) → same conversation."
## Why
Path-keyed memory is fragile. A user renames `src/foo.py` to `src/bar.py`, and the curation snapshot, the per-file conversation log, and the summary cache all silently orphan. The data is still on disk; the *index* lost its key.
Inode-keyed memory survives:
- Rename in place (`mv src/foo.py src/bar.py`) — same inode.
- Move across directories (`mv src/foo.py lib/foo.py`) — same inode on the same filesystem.
- Editor refactor that preserves the file content.
It does NOT survive:
- `git checkout` to a different commit (inode may change on checkout depending on filesystem).
- `rm` + recreate — new inode, new identity.
## What this means in practice
- Any `FileItem`, `ContextPreset`, or per-file cache field that tracks durable state has a `file_id: str = "{st_dev}:{st_ino}"` field populated at load time.
- Lookups prefer `file_id`; fallback to fuzzy match on basename + directory tree.
- The schema migration: existing path-only files get a `file_id` added on first read; the path field stays for human-readable display.