@vib795/agent-memory 0.6.2 → 0.6.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vib795/agent-memory",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "description": "Durable cross-repo knowledge graph for GitHub Copilot and Claude Code. Markdown source of truth, disposable SQLite index, zero runtime dependencies.",
   "keywords": [
     "github-copilot",

package/skills/handoff/SKILL.md

@@ -55,6 +55,10 @@ Write-Output "--- GIT ---"
 Write-Output "ROOT=$(git rev-parse --show-toplevel 2>$null)"
 Write-Output "BRANCH=$(git branch --show-current 2>$null)"
 Write-Output "HEAD=$(git rev-parse --short HEAD 2>$null)"
+Write-Output "--- BRANCHES ---"
+git branch --sort=-committerdate --format='%(refname:short)' 2>$null | Select-Object -First 10
+Write-Output "--- LOG ---"
+git log --oneline -8 2>$null
 Write-Output "--- STATUS ---"
 git status --porcelain 2>$null
 Write-Output "UTC=$([DateTime]::UtcNow.ToString('yyyy-MM-ddTHH:mm:ssZ'))"
@@ -70,6 +74,8 @@ echo "--- GIT ---"
 echo "ROOT=$(git rev-parse --show-toplevel 2>/dev/null)"
 echo "BRANCH=$(git branch --show-current 2>/dev/null)"
 echo "HEAD=$(git rev-parse --short HEAD 2>/dev/null)"
+echo "--- BRANCHES ---"; git branch --sort=-committerdate --format='%(refname:short)' 2>/dev/null | head -10
+echo "--- LOG ---"; git log --oneline -8 2>/dev/null
 echo "--- STATUS ---"; git status --porcelain 2>/dev/null
 echo "UTC=$(date -u +%Y-%m-%dT%H:%M:%SZ)"
 ```
@@ -77,6 +83,12 @@ echo "UTC=$(date -u +%Y-%m-%dT%H:%M:%SZ)"
 If the directory is not a git repository, `ROOT`/`BRANCH`/`HEAD` come back empty.
 That is not an error. Record the working directory path and omit the git fields.
 
+`BRANCHES` is there because the current branch is rarely the whole story. Work that
+stages a change across two branches — one holding the old configuration for a first
+run, another carrying the new one — leaves the second branch invisible to
+`--show-current`, and a branch you were never shown is a branch you cannot record.
+Read the list before writing Execution protocol.
+
 ---
 
 ## Step 2 — Identify the thread
@@ -132,6 +144,17 @@ Written for a reader with zero prior context.
 Things not discoverable by reading the code: environment restrictions,
 unavailable tooling, plan limits, deadlines, taste calls already settled.
 
+## Execution protocol
+
+The sequence this work is run in, when the sequence is not obvious from the code.
+Branch choreography, pipeline order, which environment goes first, what has to be
+staged before what, what must be true before a step is safe to repeat.
+
+Write the shape of the operation, not this run's position in it. "Run the pipeline
+from a branch holding the old configuration, then from the working branch with the
+new one" belongs here. "Dev is done, UAT is next" does not — that is Current task
+state. Mandatory. `None.` when the work genuinely has no ordering.
+
 ## Rejected approaches
 
 What was tried and why it failed. Mandatory. This is the section that stops the
@@ -175,7 +198,8 @@ These separate a useful handoff from a readable paragraph that still leaves ques
    inferred with `inferred:` so the next agent knows to verify it.
 6. Never inline a diff or a patch. List changed files with one line each.
 7. Soft target 150 lines. On overflow, move detail into `<id>.detail.md` and
-   reference it. Never drop Decisions or Rejected approaches to hit the target.
+   reference it. Never drop Decisions, Execution protocol, or Rejected approaches
+   to hit the target.
 8. Empty sections say `None.` They are never deleted. A missing section reads as
    an oversight; an explicit `None.` reads as a fact.
 
@@ -252,6 +276,13 @@ request, which is the only reason this step belongs here rather than in its own
 <!-- extraction-rules:start -->
 - A node is durable only if it will still be true next month. Task state is not
   durable and belongs in a handoff file, not in the graph.
+- A repeatable **procedure** is durable even though it reads like task state, and it
+  is the exception most often missed. "Run the pipeline from a branch holding the old
+  configuration, then from the working branch carrying the new one" is a `convention`:
+  it will be true the next time anyone does this. The test is whether the sentence
+  describes *this run* — not durable — or *how this kind of run is done* — durable.
+  Branch choreography, deploy ordering and staging sequences all pass that test and
+  are routinely dropped because the previous rule makes them look like status.
 - Every `decision` node carries its why and its rejected alternatives, or it is not
   written. Rationale is the thing that never survives re-explanation.
 - Anything the conversation did not actually establish is `confidence: inferred`,
@@ -303,7 +334,19 @@ describe the same thing and the user should know.
 
 ---
 
-## Step 8 — Print the pickup line
+## Step 8 — Print the pickup lines
+
+Two different jobs pick up a handoff, and one line cannot serve both.
+
+**Continuing** is the same work in another window: same repository, same branch, the
+Next action is the next thing to do.
+
+**Replicating** is the same *kind* of work in a different repository. There the Next
+action is wrong by construction — it names branches, paths and environments that
+belong to the repo this file was written in. An agent told to "follow the Next
+action" in a different repo will either execute the wrong step or go read the
+original repo off disk to work out what was meant, and both burn the user's credits
+to arrive somewhere worse than a cold start.
 
 End your reply with exactly this, and nothing after it:
 
@@ -311,21 +354,34 @@ End your reply with exactly this, and nothing after it:
 Handoff written: <absolute path to id.md>
 Thread: <id> (<created|updated>)
 
-Paste this in the other window:
+Continue in another window (same repo):
 Read <absolute path to id.md> and continue this work. Follow the Next action.
+
+Replicate in a different repo:
+Read <absolute path to id.md>. It describes work done in <repo name>. Do the
+equivalent here: follow Execution protocol, and re-derive every specific — branch
+names, file paths, module versions — from this repository. Do not open <repo name>
+and do not assume its Next action applies. Tell me the plan before you edit.
 ```
 
+Print both. The user knows which window they are pasting into; you do not.
+
 ---
 
 ## Self-check before you write
 
-Answer all five. If any is no, fix the file before writing it.
+Answer all six. If any is no, fix the file before writing it.
 
 1. Could a fresh agent execute **Next action** from this file alone?
-2. Does every decision state why, and what was rejected?
-3. Is Rejected approaches non-empty, or explicitly `None.`?
-4. Is every claim anchored to a path or a decision number?
-5. Is there a single secret, token, or connection string left in the body?
+2. Could an agent **in a different repository** replicate this work from this file
+   alone, without opening the repo it was written in? If it would have to go read
+   the original source to understand the shape of the change, Execution protocol is
+   too thin. This is the question that catches a handoff which reads well and is
+   still not portable.
+3. Does every decision state why, and what was rejected?
+4. Is Rejected approaches non-empty, or explicitly `None.`?
+5. Is every claim anchored to a path or a decision number?
+6. Is there a single secret, token, or connection string left in the body?
 
 ---
 

package/skills/remember/SKILL.md

@@ -41,8 +41,14 @@ Invoke this yourself the moment one of these has just happened, in the same turn
 
 - a **decision** was settled, and the reasons and rejected options are still in view
 - a **constraint** surfaced — a blocked tool, a policy, an environment restriction
+- a **tool you reached for was not there** — not on `PATH`, not installed, not
+  permitted. A command that failed because the machine does not have it is a
+  `constraint`, and an unrecorded one is a tool call you will spend again in every
+  future session on that machine
 - a **root cause** was found, as opposed to a symptom worked around
 - a **convention** was agreed, or discovered by reading the code
+- a **procedure** ran end to end and worked — the order of the steps is now known,
+  and it is about to be forgotten
 
 Do not capture on a timer, on a tool count, or at every reply. Those produce volume,
 and volume is what makes a graph useless — a store full of task chatter is worse than
@@ -78,6 +84,13 @@ most turns.
 <!-- extraction-rules:start -->
 - A node is durable only if it will still be true next month. Task state is not
   durable and belongs in a handoff file, not in the graph.
+- A repeatable **procedure** is durable even though it reads like task state, and it
+  is the exception most often missed. "Run the pipeline from a branch holding the old
+  configuration, then from the working branch carrying the new one" is a `convention`:
+  it will be true the next time anyone does this. The test is whether the sentence
+  describes *this run* — not durable — or *how this kind of run is done* — durable.
+  Branch choreography, deploy ordering and staging sequences all pass that test and
+  are routinely dropped because the previous rule makes them look like status.
 - Every `decision` node carries its why and its rejected alternatives, or it is not
   written. Rationale is the thing that never survives re-explanation.
 - Anything the conversation did not actually establish is `confidence: inferred`,
@@ -97,7 +110,7 @@ Types:
 |---|---|
 | `system` | how a thing works, anchored to a `path:line` |
 | `decision` | what was chosen, why, and what was rejected |
-| `convention` | how this codebase does something, and the gotcha |
+| `convention` | how this codebase does something, and the gotcha — including multi-step procedures, branch choreography, and deploy ordering |
 | `constraint` | what the environment or the org forbids |
 
 ---

package/src/cli.js

@@ -164,6 +164,26 @@ function cmdSetup() {
     );
   }
 
+  // Naming what did not install is the whole point. A run that silently installs
+  // eleven of twelve reads as a success and sends the user back to an editor that is
+  // still missing a skill.
+  if (r.failed.length) {
+    lines.push('', '  Failed:');
+    for (const f of r.failed) lines.push(`    [failed] ${f.path} — ${f.error}`);
+    lines.push(
+      '',
+      '  A path that will not clear is usually a leftover link from an install that has',
+      '  since moved. `agent-memory uninstall` reclaims those, then run setup again.',
+    );
+  }
+  if (r.compactError) {
+    lines.push(
+      '',
+      `  Skills are installed, but refreshing the /recall description failed: ${r.compactError}`,
+      '  Run `agent-memory index` then `agent-memory compact` to retry just that step.',
+    );
+  }
+
   return {
     ok: true,
     ...r,

package/src/setup.js

@@ -55,11 +55,45 @@ function clear(path) {
       // end stay put — which is exactly what passing `recursive` here would risk.
       rmdirSync(path);
     }
+    // `force` tells rmSync to swallow ENOENT, and a junction whose target is gone can
+    // answer the stat rmSync makes with ENOENT while the reparse point itself stays on
+    // disk. The removal then reports success and changes nothing, after which
+    // symlinkSync fails EEXIST and the copy fallback lands on a path that still
+    // exists. Checking is what turns that silent no-op into an error naming the path.
+    if (isLink(path)) rmdirSync(path);
   } else if (existsSync(path)) {
     rmSync(path, { recursive: true, force: true });
   }
 }
 
+/**
+ * Decide whether a skill link at a path we manage was put there by this tool.
+ *
+ * Identity cannot be "points at where we live right now". An install that has since
+ * moved, or a checkout that was deleted, leaves a link that test would disown — and a
+ * disowned link is unreclaimable: `uninstall` keeps it as "not ours" and `setup`
+ * cannot replace what it will not clear, so the user is left holding a broken link
+ * that no command in this tool will fix.
+ */
+function ownsLink(link, name) {
+  let dest;
+  try {
+    dest = resolve(readlinkSync(link));
+  } catch {
+    // A link sitting at one of our paths whose target cannot even be read is ours to
+    // clear. Nothing downstream can use it either.
+    return true;
+  }
+  if (dest === join(packagedSkillsDir(), name)) return true;
+  // Dangling. Nothing is lost by reclaiming a link that points nowhere, and leaving it
+  // is precisely what deadlocks both commands.
+  if (!existsSync(dest)) return true;
+  // Live, but pointing into some other agent-memory tree — an older global install, or
+  // a checkout the user set up from. The signature is that its parent holds all three
+  // of our skills, which a hand-written skill directory would not.
+  return SKILLS.every((s) => existsSync(join(dirname(dest), s, 'SKILL.md')));
+}
+
 /**
  * Link one skill into one agent directory.
  *
@@ -130,7 +164,6 @@ export function danglingSkillLinks() {
  * that indexed them; removing them is a separate, deliberate act.
  */
 export function unlinkSkills() {
-  const packaged = packagedSkillsDir();
   const removed = [];
   const kept = [];
 
@@ -141,11 +174,9 @@ export function unlinkSkills() {
         if (!existsSync(link) && !isLink(link)) continue;
         let owned = false;
         try {
-          owned = isLink(link)
-            ? resolve(readlinkSync(link)) === join(packaged, name)
-            : existsSync(join(link, 'SKILL.md'));
+          owned = isLink(link) ? ownsLink(link, name) : existsSync(join(link, 'SKILL.md'));
         } catch {
-          // A link we cannot read is a link we cannot claim. Leave it.
+          // A directory we cannot stat is one we cannot claim. Leave it.
           owned = false;
         }
         if (owned) {
@@ -182,15 +213,30 @@ export function setup({ compactFn } = {}) {
   const targets = installableTargets();
   const installed = [];
   const copies = [];
+  const failed = [];
 
   for (const target of targets) {
     for (const name of SKILLS) {
-      const r =
-        target.kind === 'skill-dir'
-          ? linkSkill(name, target.dir)
-          : writePromptFile(name, target.dir);
-      installed.push({ ...r, target: target.id, label: target.label });
-      if (r.mode === 'copy') copies.push(r);
+      // Isolated per skill. One unwritable target used to abort the whole run and
+      // discard the report with it, so a user whose `.copilot` link was wedged got no
+      // output at all and no hint that the other eleven had been fine. A failure here
+      // is data to print, not a reason to stop.
+      try {
+        const r =
+          target.kind === 'skill-dir'
+            ? linkSkill(name, target.dir)
+            : writePromptFile(name, target.dir);
+        installed.push({ ...r, target: target.id, label: target.label });
+        if (r.mode === 'copy') copies.push(r);
+      } catch (err) {
+        failed.push({
+          name,
+          target: target.id,
+          label: target.label,
+          path: join(target.dir, target.kind === 'skill-dir' ? name : `${name}.prompt.md`),
+          error: err.message,
+        });
+      }
     }
   }
 
@@ -209,11 +255,25 @@ export function setup({ compactFn } = {}) {
 
   // compact is passed in so this module does not pull the database into memory just
   // to make some symlinks.
-  const result = compactFn ? compactFn() : null;
+  //
+  // Its failure must not sink the run. Linking is already done and written to disk by
+  // this point, so throwing here would throw away an accurate report of work that
+  // actually happened and leave the user with no idea any of it succeeded. compact
+  // touches every registered skill path, which is exactly the set most likely to hold
+  // a stale entry, so it is the step most likely to throw.
+  let result = null;
+  let compactError = null;
+  try {
+    result = compactFn ? compactFn() : null;
+  } catch (err) {
+    compactError = err.message;
+  }
   return {
     targets,
     installed,
     copies,
+    failed,
+    compactError,
     skillPaths,
     home: agentHome(),
     digest: result?.digest ?? null,