@imunitic/synapse 0.1.0-experimental → 0.1.2

package/bin/synapse-setup.cjs

@@ -80,10 +80,43 @@ function readObsidianPluginData() {
   return data;
 }
 
+// The manifest recording exactly which names this tool wrote into a given
+// destination on the prior run -- diffed against the current run's names
+// so a renamed or removed skill/command is deleted instead of left behind
+// as an orphan forever. Scoped strictly to names a previous manifest
+// actually listed: anything else living in the same directory (a skill
+// from a different source, or the user's own) was never in that manifest
+// and is never touched. Lives inside `destRoot` itself, as a dotfile --
+// no `.md` extension and not a `{name}/SKILL.md` subdirectory, so no
+// harness's own skill/command discovery mistakes it for one of ours.
+const MANAGED_MANIFEST = ".synapse-managed.json";
+
+function pruneStale(destRoot, currentNames) {
+  const manifestPath = path.join(destRoot, MANAGED_MANIFEST);
+  let previous = [];
+  if (fs.existsSync(manifestPath)) {
+    try {
+      previous = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+    } catch {
+      previous = [];
+    }
+  }
+  const current = new Set(currentNames);
+  for (const name of previous) {
+    if (current.has(name)) continue;
+    fs.rmSync(path.join(destRoot, name), { recursive: true, force: true });
+  }
+  fs.mkdirSync(destRoot, { recursive: true });
+  fs.writeFileSync(manifestPath, JSON.stringify(currentNames, null, 2) + "\n");
+}
+
 // Copies every shared SKILL.md into `destRoot/{name}/SKILL.md`, verbatim
 // unless `transform` is given. Each skill gets its own uniquely-named
 // subdirectory, so overwriting ours on every run never touches anything a
 // harness's own skill discovery also finds there under a different name.
+// Returns the names written -- pruning stale ones is the caller's job,
+// since a destRoot shared with another source (Codex's own skills, on top
+// of these) needs the combined set before it can prune safely.
 function copySkills(destRoot, transform) {
   const src = path.join(PKG_ROOT, "skills");
   const names = fs
@@ -96,7 +129,7 @@ function copySkills(destRoot, transform) {
     fs.mkdirSync(destDir, { recursive: true });
     writeMaybeTransformed(path.join(src, name, "SKILL.md"), path.join(destDir, "SKILL.md"), transform);
   }
-  return names.length;
+  return names;
 }
 
 function copyCommands(destRoot, transform) {
@@ -106,7 +139,7 @@ function copyCommands(destRoot, transform) {
   for (const name of names) {
     writeMaybeTransformed(path.join(src, name), path.join(destRoot, name), transform);
   }
-  return names.length;
+  return names;
 }
 
 function writeMaybeTransformed(srcPath, destPath, transform) {
@@ -177,9 +210,13 @@ function mergeHooksInto(existingHooks, rendered, hookBin) {
 function configureClaude() {
   const hookBin = resolveHookBin();
 
-  const skillCount = copySkills(path.join(os.homedir(), ".claude", "skills"));
-  const commandCount = copyCommands(path.join(os.homedir(), ".claude", "commands"));
-  console.log(`installed ${skillCount} skills, ${commandCount} commands to ~/.claude`);
+  const skillsDest = path.join(os.homedir(), ".claude", "skills");
+  const skillNames = copySkills(skillsDest);
+  pruneStale(skillsDest, skillNames);
+  const commandsDest = path.join(os.homedir(), ".claude", "commands");
+  const commandNames = copyCommands(commandsDest);
+  pruneStale(commandsDest, commandNames);
+  console.log(`installed ${skillNames.length} skills, ${commandNames.length} commands to ~/.claude`);
 
   const settingsPath = path.join(os.homedir(), ".claude", "settings.json");
   let settings = {};
@@ -283,7 +320,7 @@ function configureCodex() {
   console.log(`configured ${hooksPath}`);
 
   const skillsDestRoot = path.join(os.homedir(), ".codex", "skills");
-  const sharedCount = copySkills(skillsDestRoot);
+  const sharedNames = copySkills(skillsDestRoot);
   const codexSkillsSrc = path.join(PKG_ROOT, "harness", "codex", "skills");
   const codexNames = fs
     .readdirSync(codexSkillsSrc, { withFileTypes: true })
@@ -293,7 +330,8 @@ function configureCodex() {
   for (const name of codexNames) {
     fs.cpSync(path.join(codexSkillsSrc, name), path.join(skillsDestRoot, name), { recursive: true, force: true });
   }
-  console.log(`installed ${sharedCount + codexNames.length} skills to ${skillsDestRoot}`);
+  pruneStale(skillsDestRoot, [...sharedNames, ...codexNames]);
+  console.log(`installed ${sharedNames.length + codexNames.length} skills to ${skillsDestRoot}`);
 
   const pluginData = readObsidianPluginData();
   if (!pluginData.enableInsecureServer || !pluginData.insecurePort) {
@@ -365,12 +403,13 @@ function configureOpencode() {
   fs.writeFileSync(pluginDest, pluginSource);
   console.log(`installed ${pluginDest}`);
 
-  const skillCount = copySkills(path.join(os.homedir(), ".config", "opencode", "skill"), opencodeToolNameTransform);
-  const commandCount = copyCommands(
-    path.join(os.homedir(), ".config", "opencode", "command"),
-    opencodeToolNameTransform
-  );
-  console.log(`installed ${skillCount} skills, ${commandCount} commands to ~/.config/opencode`);
+  const skillsDest = path.join(os.homedir(), ".config", "opencode", "skill");
+  const skillNames = copySkills(skillsDest, opencodeToolNameTransform);
+  pruneStale(skillsDest, skillNames);
+  const commandsDest = path.join(os.homedir(), ".config", "opencode", "command");
+  const commandNames = copyCommands(commandsDest, opencodeToolNameTransform);
+  pruneStale(commandsDest, commandNames);
+  console.log(`installed ${skillNames.length} skills, ${commandNames.length} commands to ~/.config/opencode`);
 
   const pluginData = readObsidianPluginData();
   if (!pluginData.enableInsecureServer || !pluginData.insecurePort) {

package/commands/synapse-init.md

@@ -97,7 +97,7 @@ yours and cannot be scripted because what counts as signal differs per codebase.
   (hash, digest, `## Sources` mirror, PUT), `synapse push-nodes`, `synapse build-index`,
   `synapse build-project-index`.
 
-**The work directory** defaults to `~/.claude/synapse-work/{repo}@{branch}/`, created on demand, and
+**The work directory** defaults to `~/.cache/synapse/work/{repo}@{branch}/`, created on demand, and
 holds `manifest.tsv`, `all.txt`, `lists/`, the authored `b-NN.md` bodies and the coverage files. Override with `$SYNAPSE_WORK_DIR` if you need to. Two things never to do: point it
 at the repo (`synapse` runs from inside the repo, so its working files would land in the user's
 checkout) or at the vault (Obsidian would index a file list that runs to six figures of lines).

package/commands/synapse-rebuild-diff.md

@@ -85,7 +85,7 @@ this command when it does. What no longer happens is arriving here merely becaus
   because it is not this checkout's namespace to diff at all. Never conflate the two: a non-ancestor
   baseline on a branch-identity match still proceeds normally, per the "One mechanical fact about
   branches" section above.
-- The work directory (`$SYNAPSE_WORK_DIR`, default `~/.claude/synapse-work/{repo}@{branch}/`) ideally
+- The work directory (`$SYNAPSE_WORK_DIR`, default `~/.cache/synapse/work/{repo}@{branch}/`) ideally
   holds the `manifest.tsv` from the original build. Without it, new paths cannot be classified as
   auto-claimable, and clustering decisions have to be re-derived — say so rather than proceeding as if
   nothing were missing. `synapse/{repo}@{branch}/_manifest.tsv` is the fallback copy.

package/commands/synapse-status.md

@@ -60,7 +60,8 @@ step patches a compiled design note with a `> Compiled task: [[...]]` line right
 **3. Design notes (any status) with a non-empty `## Open Questions`.** Match the heading followed by
 at least one bullet -- a heading with nothing under it (fully pruned, per the Ready-gate convention
 `/synapse-design-note` now follows) doesn't count as open. Since this section spans every status,
-each line in the composed report also shows *which* status the note is currently in:
+each line in the composed report also shows *which* status the note is currently in, and whether it
+has a compiled task note:
 
 ```
 {"and": [
@@ -69,16 +70,17 @@ each line in the composed report also shows *which* status the note is currently
 ]}
 ```
 
-`regexp` is boolean-only (no captured groups), so getting each match's actual status needs a second
-pass. Run the same query three more times, `and`-ed with `{"regexp": ["## Status\\nDiscussing", ...]}`
-/ `Ready` / `Reference` respectively, to sort the matches from the first query into the three known
-statuses without a body read. **A design note written before `## Status` was standardized on those
-exact three words can carry free text there instead** (e.g. `Superseded by [[...]]`) -- it matches
-the first query but none of the three status-scoped ones. Whatever's left over after removing the
-Discussing/Ready/Reference matches from the first query's full result set is exactly this case:
-report those under a fourth bucket, "Other", rather than silently dropping them -- surfacing an odd
-note beats losing it, the same reasoning behind reporting a 0-unchecked task instead of hiding it
-(see Query 4 below).
+Do not chain further `and`/`regexp` conditions onto this query to sort matches by status -- compound
+`regexp` conditions against `content` have been observed to return results that are logically
+impossible (a query with strictly more AND-ed conditions returning *more* matches than one with
+fewer), so any query beyond a single `glob` + single `regexp` pair is unverified and not to be
+trusted here. Instead, `mcp__obsidian__vault_read` each match directly and take two things from the
+result, no second query needed for either: the line following `## Status` in `content` (normally
+`Discussing`/`Ready`/`Reference`, but a note written before the three-word convention can carry free
+text instead, e.g. `Superseded by [[...]]` -- report that verbatim rather than forcing it into a
+bucket, surfacing an odd note beats losing it) and, from the `links` array, any path under `tasks/`
+-- that's the compiled task, if one exists, with no separate `Compiled task:` regex needed since a
+resolved wikilink already appears in `links` regardless of where in the body it's written.
 
 **4. Open task notes with at least one unchecked item.** Task notes carry `status:` in frontmatter,
 unlike design notes -- filter there first:
@@ -104,10 +106,11 @@ note past `REVIEW` on its own:
 
 One section per category, in the order above. Each line names the note (title, or filename if no
 `title` frontmatter) plus the one identifying detail that category needs. The Open Questions section
-is the one place a note's status also belongs on the line -- every other section's heading already
-implies it (the "Discussing" section only ever holds `Discussing` notes), but Open Questions spans
-every status (`Discussing`/`Ready`/`Reference`/the "Other" catch-all from Query 3 above), so put the
-status first, before the title, so it's the first thing scanned:
+is the one place a note's status and compiled-task link also belong on the line -- every other
+section's heading already implies status (the "Discussing" section only ever holds `Discussing`
+notes) and compiled-task-ness (the "Ready, not yet compiled" section only ever holds notes without
+one), but Open Questions spans every status and both compiled and uncompiled notes, so put the status
+first, before the title, so it's the first thing scanned:
 
 ```
 ## Discussing
@@ -117,7 +120,7 @@ status first, before the title, so it's the first thing scanned:
 - {title}
 
 ## Open questions
-- **{status}** — {title}
+- **{status}** — {title} — {compiled task title, or "not compiled"}
 
 ## In progress (unchecked items)
 - {title} ({N} unchecked)

package/harness/codex/skills/synapse-init/SKILL.md

@@ -97,7 +97,7 @@ yours and cannot be scripted because what counts as signal differs per codebase.
   (hash, digest, `## Sources` mirror, PUT), `synapse push-nodes`, `synapse build-index`,
   `synapse build-project-index`.
 
-**The work directory** defaults to `~/.claude/synapse-work/{repo}@{branch}/`, created on demand, and
+**The work directory** defaults to `~/.cache/synapse/work/{repo}@{branch}/`, created on demand, and
 holds `manifest.tsv`, `all.txt`, `lists/`, the authored `b-NN.md` bodies and the coverage files. Override with `$SYNAPSE_WORK_DIR` if you need to. Two things never to do: point it
 at the repo (`synapse` runs from inside the repo, so its working files would land in the user's
 checkout) or at the vault (Obsidian would index a file list that runs to six figures of lines).

package/harness/codex/skills/synapse-rebuild-diff/SKILL.md

@@ -85,7 +85,7 @@ this skill when it does. What no longer happens is arriving here merely because
   because it is not this checkout's namespace to diff at all. Never conflate the two: a non-ancestor
   baseline on a branch-identity match still proceeds normally, per the "One mechanical fact about
   branches" section above.
-- The work directory (`$SYNAPSE_WORK_DIR`, default `~/.claude/synapse-work/{repo}@{branch}/`) ideally
+- The work directory (`$SYNAPSE_WORK_DIR`, default `~/.cache/synapse/work/{repo}@{branch}/`) ideally
   holds the `manifest.tsv` from the original build. Without it, new paths cannot be classified as
   auto-claimable, and clustering decisions have to be re-derived — say so rather than proceeding as if
   nothing were missing. `synapse/{repo}@{branch}/_manifest.tsv` is the fallback copy.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imunitic/synapse",
-  "version": "0.1.0-experimental",
+  "version": "0.1.2",
   "description": "Memory for Claude Code, Codex CLI, and OpenCode: a durable Obsidian vault plus a per-repo code graph.",
   "repository": {
     "type": "git",
@@ -22,9 +22,9 @@
     "*.conf.template"
   ],
   "optionalDependencies": {
-    "@imunitic/synapse-darwin-arm64": "0.1.0-experimental",
-    "@imunitic/synapse-linux-x64": "0.1.0-experimental",
-    "@imunitic/synapse-linux-arm64": "0.1.0-experimental"
+    "@imunitic/synapse-darwin-arm64": "0.1.2",
+    "@imunitic/synapse-linux-x64": "0.1.2",
+    "@imunitic/synapse-linux-arm64": "0.1.2"
   },
   "license": "SEE LICENSE IN LICENSE"
 }

package/skills/synapse-node/SKILL.md

@@ -76,7 +76,7 @@ needs one.
    `built_at`, `commit`, `stale: false`, and preserving `## Notes` — belongs to
    `synapse write-node`, because a hub node's `sources` can no more be *emitted* into a tool call
    than read into a window. Let `$W` be the project's work directory,
-   `~/.claude/synapse-work/{repo}@{branch}/`.
+   `~/.cache/synapse/work/{repo}@{branch}/`.
 
    - **Get the node's path list into a file, never into context:**
 

package/skills/synapse-vault/SKILL.md

@@ -103,5 +103,5 @@ and regenerated by the `synapse-node` skill — never hand-edited, because the w
 `sources` hashes, `sources_digest` and the `## Sources` mirror, and a hand edit desynchronises
 them. `_profile.txt` and `_manifest.tsv` are human-readable and may be edited directly. The
 machine-only artifacts -- `_index.bin`, `_refs.tsv`, `_tags_cache.bin` -- are not here at all: they
-live in `~/.claude/synapse-work/{repo}@{branch}/`, because they are derived, rebuildable and large,
+live in `~/.cache/synapse/work/{repo}@{branch}/`, because they are derived, rebuildable and large,
 and the vault is version-controlled.