@imunitic/synapse 0.0.1-test.0

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

@@ -0,0 +1,315 @@
+---
+name: synapse-rebuild-diff
+description: Manually bring a repo's Synapse namespace back in line after major same-branch drift — a pull, a rebase, or a long absence. Triages each drifted node into reseat / patch-from-diff / re-orient rather than rebuilding everything. Refuses outright on a cross-branch mismatch; for a full rebuild from scratch, use the synapse-rebuild-full skill instead.
+---
+
+# Synapse Rebuild Diff: Reconcile a Namespace After Same-Branch Drift
+
+The synapse-init skill builds a namespace. The two staleness tiers and `synapse query drift` *detect*
+that it has moved. This skill is the deliberate, human-invoked repair for the case where enough has
+moved that lazy per-read regeneration is the wrong instrument.
+
+**Same-branch only.** Every scenario below happens on the branch the namespace already describes —
+a pull, a rebase, time passing, your own hand-written commits. None of them involve the current
+checkout being on a *different* branch than the namespace's own recorded `branch:` field. If it is,
+this skill refuses outright rather than attempting a diff — see the branch-identity check under
+Prerequisites. Comparing one branch's tree against another isn't drift, it's just two unrelated
+states, and none of the triage classes below (reseat / patch / re-orient) were built for that.
+
+## When to run it
+
+Manually, when you already expect major drift:
+
+- **A plain `pull`** that landed a meaningful number of commits — fast-forward, same branch throughout.
+- **A `pull --rebase`** — your local commits get new SHAs, so `synapse query drift` will likely
+  report the baseline as "not an ancestor of HEAD". That's expected here, not a sign of anything
+  wrong: you were on the same branch the whole time, only its history got rewritten.
+- **A large merge landing in your current branch** — another branch's tip merged in via `git merge`.
+  Still same-branch throughout: `HEAD` gains a merge commit, it doesn't move to a different branch.
+- **A long absence** — weeks or months of other people's commits landed while you were elsewhere, on
+  the same branch.
+- **You wrote a lot of code by hand.** The plainest case and probably the most common: days of ordinary
+  work in your own branch, in your own editor, with no model involved. Tier 1 only fires on an edit
+  *in this session*, so none of it was flagged as it happened. `stale` will still catch content
+  changes to files a node already claims — but it reports a rename as "gone", and a **newly added
+  file it cannot see at all**, because a path in no node's `sources` has nothing to compare against.
+  Real feature work adds files, so this is exactly where the graph goes quietly out of date. Same
+  applies to anything else that bypasses the session: an IDE refactor (which produces both bad cases
+  at once — renames *and* new paths), a `sed -i`, generated code that the build rewrote from a
+  schema, a dependency bump, or a moved submodule pointer.
+
+Do **not** run it after an ordinary pull. Tier 1 flags what this session edited, the `synapse-node`
+skill regenerates a node lazily when its body is actually needed, and `synapse query drift` is the
+cheap check that tells you whether anything more is warranted. This skill exists for when the answer
+is clearly yes.
+
+**A large job is the expected outcome, not a warning sign.** On a monorepo with a hundred thousand
+files and heavy traffic, most of the graph moving at once is simply what the situation looks like, and
+forty nodes in *re-orient* is a normal shape for this skill rather than a reason to hesitate. Nothing
+invokes this automatically — a human asked for it, knowing their own repo and why they are here. So
+report the size, then **do the work**. Do not recommend against a rebuild on the grounds that it is
+expensive, do not offer a reduced version of it unasked, and do not describe replacing the graph as
+destructive: replacing it is the entire point. Volunteer a smaller option only where a *correctness*
+reason argues for one, and even then do the full job if the human says so.
+
+**One mechanical fact about branches, because it is not guessable.** A namespace is keyed by repo
+*and branch* (`synapse/{repo}@{branch}/`), so each branch has its own or has none. A branch switch
+therefore no longer invalidates anything: the graph you built on the mainline stays intact and keeps
+describing the mainline, and the branch you switched to simply has no namespace until someone runs
+the synapse-init skill there. That is an ordinary state, not a problem to fix.
+
+So the massive-drift case this skill exists for is now the *unusual* one rather than the norm. It
+still happens — a branch can be checked out inside any worktree, and a long-lived branch gets rebased
+onto a moved trunk, which leaves the recorded baseline off the current line exactly as a branch switch
+used to. Read a "not an ancestor of HEAD" warning as "history moved under this graph", and reach for
+this skill when it does. What no longer happens is arriving here merely because you changed branch.
+
+## Prerequisites
+
+- The namespace must exist. If `synapse/{repo}@{branch}/Index.md` is absent, this is a first build — use
+  the synapse-init skill.
+- **Branch-identity check — hard stop, run this before anything else, including drift/grounding.**
+  Compare the current checkout's branch against the namespace's own recorded `branch:` frontmatter
+  field:
+  ```sh
+  current_branch="$(git symbolic-ref --short HEAD)"
+  ns_branch="$(grep -m1 '^branch:' "synapse/{repo}@{branch}/Index.md" \
+      | sed -e 's/^branch: *//' -e 's/^"//' -e 's/"$//')"
+  ```
+  If they don't match, **refuse immediately** — do not run `synapse query drift`, do not read
+  anything else. Say plainly that this namespace describes a different branch than the current
+  checkout, and point at the synapse-init skill (if the current branch has no namespace of its own)
+  or at checking out the branch/worktree the namespace actually describes. This is a distinct, harder
+  check than the "baseline is not an ancestor of HEAD" ancestry signal below — that one is a *soft*,
+  informational finding (expected after a same-branch `pull --rebase`); this one is a hard refusal,
+  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
+  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.
+- Read `synapse/{repo}@{branch}/_profile.txt` if it exists, before triaging anything. It records the
+  aggregations that carried signal for this repo and the searches that came back empty.
+
+## Procedure
+
+### 1. Size the job before doing any of it
+
+```sh
+~/.synapse query drift
+~/.synapse query grounding
+```
+
+Report what it says, in the human's terms, **before** touching anything: how far the baseline is from
+HEAD (and whether it is an ancestor at all), how many nodes are flagged in each class, and how many
+added paths need a decision. Silence means nothing to rebuild — say so and stop, including when the
+repo is behind its upstream: drift prints that only alongside a finding, because an accurate graph
+plus unpulled commits is nothing to repair yet.
+
+Two answers change the plan:
+
+- **"baseline … is not an ancestor of HEAD"** — a branch switch or a reset. The file-level diff is
+  still exactly right (it compares trees, not history), but expect deletions to dominate: files that
+  exist on the built line and simply are not here.
+- **"no commit recorded"** or **"baseline … not in local history"** — those nodes cannot be diffed at
+  all. They go straight to the *re-orient* class in step 3; there is no cheaper option for them.
+
+### 2. Mechanical phase — always, and cheap
+
+```sh
+~/.synapse build-lists --reenumerate
+```
+
+`--reenumerate` matters here: without it an existing `all.txt` is reused, so a branch switch would be
+invisible to enumeration. **Read the coverage report.** On a branch switch, per-node list sizes will
+move a lot and some may reach zero.
+
+- **A node whose list is now empty** means that subsystem does not exist on this branch. **Do not
+  write it** — `synapse write-node` refuses an empty path list, and that refusal is correct. Report
+  the node and leave it in place, untouched. **Never delete a node to tidy up a branch switch:**
+  `## Notes` is human-authored, lives outside the generated fence, and is unrecoverable.
+- **Unclaimed added paths** are a judgment call: widen an existing manifest line where a path belongs
+  to a cluster that already exists, and leave a genuinely new subsystem for a new manifest line and
+  its own node. Re-run `synapse build-lists` after editing the manifest, and check coverage again.
+
+Then rebuild the reverse index so the hook and the read path agree with the new enumeration:
+
+```sh
+~/.synapse build-index
+```
+
+### 3. Triage each flagged node — reseat, patch, or re-orient
+
+**Hard requirement for the *re-orient* class, not a recommendation: invoke the `synapse-orientation`
+skill before writing one sentence of new prose for that node.** Reading the node's own source
+directly and reasoning from what you already know about the codebase is not a substitute, no matter
+how accurate or hard-won that knowledge is — a node's premises being re-derived is the same problem
+a first build faces, and it gets the same required technique, every time, not just when nothing
+faster is available. The reason this can't be skipped even by a confident, correct reading of the
+source: the skill's own verification step is to *run* something real (`synapse tags`/`synapse query`
+against a real sample) and judge the actual output, not what the source implies the output should
+be — and only an executed check can surface a gap in the tooling itself, one the source reading alone
+has no way to reveal, however carefully it's done. A node whose own subject is the tagging or
+extraction pipeline is exactly the case most tempting to shortcut this way, and exactly the case
+where doing so costs the most.
+
+`synapse-node-format` is the other skill to load before triaging, for every class, not just
+*re-orient*: the node contract — frontmatter, the crux pointer, `## Links`, `grounded_in` — the same
+one the synapse-init skill and the `synapse-node` skill write against.
+
+**The principle: compute new prose from the diff, not by re-reading the node's sources.** A node
+covering 15,000 files where 12 changed already has prose encoding the other 14,988. Re-reading it all
+is the expensive mistake this skill exists to avoid, and it also throws away hard-won findings the
+diff has nothing to say about.
+
+**Take the nodes that lost files first, and keep the full list of deleted paths in front of you for
+every node after that.** A deletion in one node is routinely the other half of an addition in
+another — a type moved from the binary into a library, a module promoted out of a `util`. Triaged in
+drift's arbitrary order, the node that *gained* the file is patched first, with no way to know the
+file came from anywhere, and the patch fills the gap with a guess. One cheap list, read once:
+
+```sh
+git diff --diff-filter=D --name-only -M <commit>..HEAD
+```
+
+**Size each node by changed lines, not by changed files.** Drift reports file counts because that is
+what it can compute without a diff, but a file count saturates immediately in a repo of small
+modules: a node of 9 files with 5 touched reads as 56% when the actual change is 199 lines out of
+2,077, and every one of them a formatting or import edit. Get the real ratio before choosing:
+
+```sh
+git diff --numstat <commit>..HEAD -- $(tr '\n' ' ' < "$W/lists/NN.txt") \
+  | awk '{a += $1; d += $2} END {print a + d}'
+```
+
+against the node's own line count, and use `synapse query sources "{Node}" --count` for the file
+count drift's numbers are relative to. Then pick one of three strategies and **say which one you
+picked and why**:
+
+**Restore the crux directive before writing any node back.** `synapse query body` returns the
+*expanded* crux — the fenced code the writer sliced — not the directive that produced it. Writing that
+straight back stores a quote of a file as it looked at the old baseline, presented as if it were
+current. So rebuild the directive from the pointer the writer recorded:
+
+```sh
+~/.synapse query field "{Node}" crux_path
+~/.synapse query field "{Node}" crux_lines
+```
+
+and replace the fenced block with `<!-- crux: <crux_path> <crux_lines> -->` so it is cut from the
+current file. One judgment goes with it: re-slicing the same range is only safe if that file did not
+change. If it did, the line numbers may now point at something else entirely — treat the crux as
+needing a fresh pointer, exactly as the prose needs a fresh sentence. A node with no `crux_path` had
+`none`, and stays that way.
+
+**The same applies to groundings, and forgetting them loses more.** `grounded_in` is frontmatter and
+its directives are stripped from the body, so a recovered body contains none — write it back as-is and
+the node's provenance is gone with no error. Recover the pointers per node:
+
+```sh
+~/.synapse query grounding "{Node}" --list   # path<TAB>lines
+```
+
+and re-emit a `<!-- grounded_in: <path> <lines> -->` for each. Run `synapse query grounding` before
+triaging: it is cheaper than the diff and sharper than a churn ratio. A **`moved`** line hands you the
+corrected range outright, no reading. A **`changed`** line points at evidence that no longer says what
+the summary claims — which is a better reason to re-read a node than any percentage, because it names
+the sentence at risk rather than the volume of change around it.
+
+**Reseat** — renames only, no content change. No reading at all. Recover the existing prose with
+`synapse query body "{Node}"`, drop its trailing `## Sources` block (the writer regenerates that),
+re-enumerate so the list holds the new paths, and write it back. Repeating this is safe: the writer
+trims the body's leading and trailing blank lines, so a reseat is idempotent rather than accreting
+padding each time. The concept did not change; only paths moved. This also
+works on a machine that never built the namespace, because the body came from the node itself rather
+than from a work-dir file.
+
+**Patch from the diff** — a small fraction of the node's *lines* changed (rule of thumb: under ~15%),
+and the file its `crux` quotes still exists. Read three things and nothing else:
+
+1. the current prose — `synapse query body "{Node}"`;
+2. `git diff --name-status -M <commit>..HEAD` restricted to that node's paths, for *which* files moved;
+3. hunks for a **bounded** selection of those files — always including any file the `crux` quotes.
+
+Then amend only the sentences the diff contradicts, and keep everything else verbatim.
+
+**A patch may say what the node now contains. It must not say where something came from** unless the
+rename is in the diff it read. Provenance is the one claim a node-restricted diff structurally cannot
+support: the other end of the move is in a different node's paths, so the diff shows an unexplained
+new file, and the plausible local origin is an invention. `git`'s rename detection is not a
+safety net here — a file that moved between modules and was rewritten on the way lands below the
+similarity threshold and shows up as a delete in one node and an add in another even under
+`-M --find-copies-harder`. Which is why deletions get read first, below.
+
+**Re-orient** — a large fraction changed, the baseline is unusable, or there is a structural signal:
+the `crux` file is gone or renamed, whole modules entered or left the node, or a package root changed
+name. Here the prose's premises are suspect, so patching would preserve a claim that is no longer
+true. Re-run this node's aggregations from `_profile.txt` (path-level, so cheap even on a hub node),
+read the few load-bearing files the aggregations point at, and re-author as the synapse-init skill
+would.
+
+**The diff must be projected as carefully as `sources` is.** `git diff` with hunks across a hub node's
+paths over hundreds of commits runs to megabytes — the same constraint that makes `sources` unreadable
+applies to the diff. So: `--name-status` for names, `--stat` to size it, and hunks only for a bounded
+selection. Never pipe an unbounded `git diff <commit>..HEAD` into a context window.
+
+### 4. Write each rebuilt node
+
+```sh
+~/.synapse write-node --title "{Node}" --summary "{one line}" \
+   --paths "$W/lists/NN.txt" --body "$W/body.md"
+```
+
+It re-records `commit`, so this checkout becomes the node's new baseline — which is what makes the next
+`drift` meaningful. **Re-check the one-line `summary`**: after a branch switch it can be wrong in kind,
+not merely stale, if the subsystem's shape differs on this line.
+
+### 5. Rebuild the projections and verify
+
+```sh
+~/.synapse build-index
+~/.synapse build-project-index
+~/.synapse query drift     # expect silence
+~/.synapse query stale     # expect silence
+~/.synapse query grounding # expect silence: re-pointed, not dropped
+~/.synapse query links --check   # expect silence: no dangling targets
+```
+
+`links --check` covers what used to be a manual instruction here: a broken `[[wikilink]]` is a valid
+link to a not-yet-existing note, so Obsidian renders it without complaint and nothing else in the
+system notices. It now reports `Node<TAB>relation -> Target (no such node)` per dangling edge.
+
+One check is still yours, because no command performs it: **every node file appears in `Index.md`**. An
+unlisted node exists and is reachable by search, but is invisible to anyone reading the map.
+
+### 6. Report what happened
+
+Per node: the strategy chosen and why. Plus what was deliberately left alone — nodes drift did not
+flag, and nodes whose sources vanished on this branch. A rebuild that silently re-authored forty nodes
+is indistinguishable, from the outside, from one that did nothing.
+
+## Guardrails
+
+- **Never `pull`, `fetch --prune`, `rebase`, `reset` or `checkout`.** The human chose this checkout;
+  this skill describes and records it. Report how far behind the upstream ref is and stop there.
+- **Never re-read a node's full sources to patch a small diff.** That is the specific waste this
+  skill is built to avoid.
+- **Know what patching cannot fix.** It keeps every sentence the diff does not contradict, so a claim
+  that was wrong when the node was *built* survives every future patch untouched — the diff has
+  nothing to say about a statement that was never true. Patching is therefore only as good as the
+  baseline prose, and a node's most likely error is not drift but an explanation invented at build
+  time. The `crux` is no longer the exposure it was — `synapse write-node` slices it out of the
+  file from a `<!-- crux: path start-end -->` directive, so it is verbatim by construction rather than
+  by instruction. What remains unguarded is the prose. A sentence asserting a *mechanism* ("X is
+  behind a mutex, which is why Y")
+  deserves more suspicion than one asserting structure — if the diff touches its file at all, verify
+  it rather than carrying it over.
+- **Never write a node with an empty path list**, and never delete a node whose sources vanished — its
+  `## Notes` is human-authored and outside the generated fence.
+- **Never hand-write frontmatter or the `## Sources` mirror.** `synapse write-node` owns them; doing
+  it by hand cannot scale to a hub node and silently drops `summary` and `commit`.
+- **Never rebuild a node drift did not flag.** Regeneration has real cost and it is not free of risk —
+  each rewrite is a chance to lose a good sentence.
+- **Say when the graph now describes a different branch than it did before**, in the final report. That
+  fact outlives the session, and the next reader has no other way to know.

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

@@ -0,0 +1,149 @@
+---
+name: synapse-rebuild-full
+description: Wipe a repo's Synapse namespace and rebuild it from scratch via the synapse-init skill, for the case where diff-driven triage isn't the right tool — the graph has drifted too far, or a clean rebuild is just wanted directly. Preserves any hand-written `## Notes` content first and auto-merges what it can back into the new nodes. For ordinary same-branch drift, use the synapse-rebuild-diff skill instead — it's cheaper and never deletes a node outright.
+---
+
+# Synapse Rebuild Full: Wipe and Rebuild a Namespace From Scratch
+
+The synapse-rebuild-diff skill triages drift node by node — reseat, patch, or re-orient — and never
+deletes anything. This skill is the other tool: it deletes the current namespace outright and
+rebuilds it from nothing via the synapse-init skill's own First-time-build procedure. Reach for it
+when the graph has drifted past the point where triage is worth it (most nodes would land in
+*re-orient* anyway), when the namespace is corrupted or was built badly, or when a clean rebuild is
+simply what's wanted — never as a reflex for ordinary drift, which the synapse-rebuild-diff skill
+handles more cheaply and without touching anything irreplaceable.
+
+**Unlike the synapse-rebuild-diff skill, this skill does not care which branch is checked out beyond
+the ordinary sense.** It isn't diffing against anything — it resolves `{repo}@{branch}` for
+whatever's currently checked out and rebuilds *that* namespace, exactly as the synapse-init skill
+does. There is no branch-identity guardrail here because there is nothing to compare against; the
+branch you're on is simply the branch being rebuilt.
+
+## When this runs
+
+Invoked whenever the user wants a repo's Synapse namespace wiped and rebuilt from scratch — no
+arguments to parse, always operates on the repo and branch containing the current working directory.
+
+## Prerequisites
+
+- Requires the `obsidian` MCP server (`mcp__obsidian__*` tools). If unreachable, say so and stop —
+  same requirement the synapse-init skill has.
+- Must be run from inside a git repository, on a named branch (not detached `HEAD`) — same
+  requirement the synapse-init skill has, since `synapse_namespace` needs a branch to key on.
+
+## Procedure
+
+### 1. Resolve the namespace
+
+Same resolution the synapse-init skill uses: repo root (`git rev-parse --show-toplevel`), namespace
+key (`{repo}@{branch}`, printed by `synapse namespace`), remote (for the index note's
+verification field).
+
+Check whether `synapse/{repo}@{branch}/Index.md` exists.
+
+- **Doesn't exist** → there is nothing to wipe. This is just a first build, not a rebuild — hand off
+  directly to the synapse-init skill and stop here. Do not run the wipe step at all in this case; it
+  would only fail on a directory that isn't there.
+- **Exists, `remote` mismatches** → belongs to a different repo sharing this key. Same refusal the
+  synapse-init skill gives in this case: stop, name both remotes, do not touch it.
+- **Exists, `remote` matches** → continue to step 2.
+
+### 2. Preview the wipe and get explicit confirmation
+
+```sh
+~/.synapse graph-wipe --dry-run
+```
+
+Report its output plainly: node count, and — the one thing this step exists to surface — how many
+nodes carry hand-written `## Notes` content that's about to be deleted, and which ones. `## Notes` is
+human-authored, lives outside every generated fence, and no rebuild regenerates it; a wipe is the one
+operation in this pair of skills that actually deletes files rather than overwriting them with
+preservation, so it earns an explicit stop here that the synapse-rebuild-diff skill deliberately does
+not have.
+
+**Get an explicit yes before continuing.** This is a hard-to-reverse filesystem operation on content
+that includes irreplaceable human prose — do not proceed past this point on an assumption, even if
+the human is the one who asked for this rebuild in the first place. Asking for it signals intent to
+rebuild; it is not itself confirmation of a delete that touches N nodes with hand-written notes
+attached, which the human hasn't seen a number for yet.
+
+### 3. Wipe
+
+Once confirmed:
+
+```sh
+~/.synapse graph-wipe
+```
+
+This deletes `synapse/{repo}@{branch}/` and, if any node had non-empty `## Notes`, first dumps that
+content verbatim to `scratchpad/{repo}@{branch} — preserved notes before full rebuild.md`. See
+`synapse graph-wipe`'s own header for the exact mechanics (belt-and-braces path check, same
+discipline `synapse graph-clean` uses for its own deletion).
+
+### 4. Rebuild from scratch
+
+Run the synapse-init skill's **First-time build** procedure (its steps 1–8) against the now-empty
+namespace, by reference rather than repeating it here — enumerate, read hint files, orientation pass,
+cluster into `manifest.tsv`, gate, write each node, build `_index.bin`, build `Index.md`. Same
+procedure, same judgment calls, nothing rebuild-specific about this phase: from the namespace's
+perspective this is identical to a first build, because as of step 3 it is one.
+
+### 5. Merge preserved notes back
+
+Skip this step entirely if step 2 found nothing preserved (no staging note was created).
+
+**Only once the new `Index.md` exists** — not during clustering, not node-by-node as nodes are
+written. Read the staging note (`scratchpad/{repo}@{branch} — preserved notes before full rebuild.md`)
+and classify each preserved note's old title + content against the finished new node list, the same
+technique the synapse-init skill's `_unassigned` sweep already uses for classifying files against an
+existing node list: read the note against the new summaries, judge which node it best fits.
+
+- **Confident match** → append the note's content into that node's `## Notes` section (every node
+  written by `synapse write-node` already carries one, empty if nothing else was there — never a
+  "create the section" case) with a one-line provenance breadcrumb: `(carried over from "{old node
+  title}" during full rebuild on {date})`. The note is losing its original context by moving to a new
+  home, and that breadcrumb is the only way a future reader recovers why it's there.
+
+  **Report the placement even though it succeeded.** Say which old node's notes went to which new
+  node, for every single one, not only the ones that failed to place. A wrong auto-placement is most
+  dangerous exactly when it's silent — this is the one class of content in the whole system marked
+  irreplaceable, and "it succeeded" is not the same claim as "it succeeded correctly."
+- **No confident match** → leave it in the staging note, and say why: no equivalent concept survived
+  the re-cluster, or more than one new node looked equally plausible. Do not guess past a stated
+  uncertainty here — a note in the wrong node is worse than a note sitting in scratchpad waiting for a
+  human to place it.
+
+Once every preserved note has been classified: if every one found a confident home, delete the
+staging note — nothing is left needing manual attention. If any remain unplaced, leave the staging
+note live containing only the leftovers, trimmed of everything that did get merged.
+
+### 6. Report
+
+- Old node count vs. new node count.
+- Whether any notes were preserved, and the outcome of every single one from step 5 (merged where, or
+  left for manual placement and why) — not just a summary count.
+- If the staging note still exists, say so explicitly and give its path — it needs a human look.
+
+## Guardrails
+
+- **Never wipe without running `--dry-run` first and getting explicit confirmation on its output.**
+  The preview step exists specifically so "how many notes are about to be deleted" is answered before
+  it happens, not after.
+- **Never invent a placement for a preserved note that isn't a confident match.** Leaving it in
+  scratchpad, flagged, is the correct outcome when nothing else is — don't fill the gap with a guess
+  to make the report look cleaner.
+- **Never merge into a node's generated region.** The merge target is always `## Notes`, appended, never
+  touching anything inside the `<!-- synapse:generated:start -->`…`<!-- synapse:generated:end -->`
+  fence — that region belongs to `synapse write-node` alone.
+- **Never treat this as the default repair path.** The synapse-rebuild-diff skill is cheaper,
+  preserves every node rather than deleting them, and is the right tool for ordinary drift. Use this
+  skill when triage genuinely isn't worth it, not as a heavier habit that replaces the lighter one.
+
+## Integration
+
+- Delegates the actual rebuild to the synapse-init skill's First-time-build procedure — this skill
+  owns only the wipe-with-preservation step before it and the note-merge step after it.
+- The wipe itself is `synapse graph-wipe` (via `synapse graph-wipe`), mirroring
+  `synapse graph-clean` as the only other destructive tool in the system.
+- Resolves the namespace the same way the synapse-init and synapse-rebuild-diff skills do -- one
+  chain, in `core/identity.zig` — never re-derives repo/branch/remote independently.

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

@@ -0,0 +1,146 @@
+---
+name: synapse-status
+description: Print a read-only report of what in Synapse Vault currently needs a human decision -- design notes still Discussing, design notes marked Ready with no compiled task yet, design notes with open questions, task notes with unchecked items, and task notes stuck in REVIEW. Use whenever the user wants a status check on the vault ("what's outstanding", "what needs my attention", "vault status", "what did we leave open"). Never modifies anything -- a report only, not a task-management action. Not for creating, continuing, or listing a specific note kind (that's the synapse-note/synapse-design-note/synapse-task-note skills' own --list modes) -- this is the one cross-cutting view over all of them at once.
+---
+
+# Synapse Status: Vault-Wide Attention Report
+
+A read-only sweep over Synapse Vault answering one question: what currently needs a human decision?
+Five categories, one pass, printed as plain chat text -- an org-agenda-style check-in, not a document
+to hand to someone else and not a live dashboard (a published Artifact has no route to the local
+Obsidian REST API, so nothing here is ever presented that way). Run it whenever the user asks for a
+vault status check, or on a recurring schedule the user has set up themselves -- never wired into
+session start: two of the five categories need a per-note body read, not just a frontmatter check,
+and unlike the vault's own index note this report is a periodic human check-in, not something the
+agent needs injected every session to behave correctly.
+
+Scoped to `designs/`/`tasks/` only -- the two folders design-note creation and task-note creation
+structurally require, so every Synapse install has them in the same shape. The free-form taxonomy
+(`inbox/`/`research/`/`scratchpad/`) is per-install customizable (see the vault's index note), not
+guaranteed to exist or mean the same thing across installs, and `inbox/` specifically is for the
+vault owner's own periodic look on their own schedule -- this report doesn't cover it.
+
+## When this runs
+
+Invoked whenever the user wants a status check on the vault ("what's outstanding", "what needs my
+attention", "vault status", "what did we leave open") -- there is no argument to parse, every run
+produces the same five-category sweep.
+
+## Prerequisites
+
+Requires the `obsidian` MCP server (`mcp__obsidian__*` tools). If unreachable, say so and stop --
+there is no local-file fallback.
+
+## Producing the report
+
+Run all five queries in parallel where the tool call shape allows it; none depends on another's
+result.
+
+**1. Design notes still `Discussing`.** Design notes carry status in-body under `## Status`, not in
+frontmatter (unlike task notes) -- a content match, scoped to `designs/`:
+
+```
+{"and": [
+  {"glob": ["designs/*", {"var": "path"}]},
+  {"regexp": ["## Status\\nDiscussing", {"var": "content"}]}
+]}
+```
+
+**2. `Ready` design notes with no compiled task yet.** The design-compilation skill's own "Linking
+back" step patches a compiled design note with a `> Compiled task: [[...]]` line right after its
+title -- "`Ready` and missing that line" is a direct signal, not fuzzy title-matching against
+`tasks/`:
+
+```
+{"and": [
+  {"glob": ["designs/*", {"var": "path"}]},
+  {"regexp": ["## Status\\nReady", {"var": "content"}]},
+  {"!": [{"regexp": ["Compiled task:", {"var": "content"}]}]}
+]}
+```
+
+**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 design-note skill's own
+Ready-gate convention) 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:
+
+```
+{"and": [
+  {"glob": ["designs/*", {"var": "path"}]},
+  {"regexp": ["## Open Questions\\n- ", {"var": "content"}]}
+]}
+```
+
+`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).
+
+**4. Open task notes with at least one unchecked item.** Task notes carry `status:` in frontmatter,
+unlike design notes -- filter there first:
+
+```
+{"in": [{"var": "frontmatter.status"}, ["TODO", "IN-PROGRESS"]]}
+```
+
+Then `mcp__obsidian__vault_read` each match and count `- [ ]` lines in the body. A match with zero
+unchecked lines (a checklist that's fully checked but hasn't been promoted to `REVIEW` yet) is still
+worth surfacing -- report it under this section with its count shown as 0, rather than silently
+dropping it, since that state itself is worth a human noticing.
+
+**5. Task notes stuck in `REVIEW`.** Frontmatter-only, no body read needed -- a fully-checked
+checklist waiting specifically on human sign-off, since the task-status skill deliberately never
+promotes a note past `REVIEW` on its own:
+
+```
+{"==": [{"var": "frontmatter.status"}, "REVIEW"]}
+```
+
+## Composing the report
+
+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:
+
+```
+## Discussing
+- {title}
+
+## Ready, not yet compiled
+- {title}
+
+## Open questions
+- **{status}** — {title}
+
+## In progress (unchecked items)
+- {title} ({N} unchecked)
+
+## Awaiting review
+- {title}
+```
+
+Omit a section entirely when it has zero matches -- matching the note-listing skill's own convention
+of leaving out empty headers -- rather than printing five headers with nothing under most of them. If
+every category is empty, say so in one line ("Vault is clear -- nothing outstanding.") instead of five
+empty headers.
+
+Print the report directly in the response, not left only in tool-call output the user would have to
+go dig for.
+
+## Constraints
+
+- Read-only end to end. Never calls `vault_write`/`vault_patch`/`vault_move`/`vault_delete`/
+  `vault_copy` -- if a step here ever seems to need one, that step is out of scope, not a case to
+  special-case around.
+- No Artifact/web-UI output. No session-start wiring. Not a new binary CLI subcommand -- every
+  category above is a plain mechanical query already reachable through `mcp__obsidian__*` tools.
+- Scoped to `designs/`/`tasks/` only -- never `inbox/`/`research/`/`scratchpad/`.