@imunitic/synapse 0.13.3 → 0.13.5

package/commands/synapse-design-note.md

@@ -205,12 +205,24 @@ Discussing | Ready | Reference
 
 ## Open Questions
 - {Anything deferred or unresolved}
+
+## References
+- [[Wikilink]] mentioned above
 ```
 
-`### Alternatives considered` and `## Open Questions` are both optional per the schema — omit
-either section entirely rather than leaving it as an empty heading, and never write it as `##
-Open Questions (optional)`: the schema and `/synapse-status`'s own query both match this exact
-heading text, and a suffixed one is invisible to both.
+`### Alternatives considered`, `## Open Questions`, and `## References` are all optional per the
+schema — omit any of them entirely rather than leaving it as an empty heading, and never write one
+as `## Open Questions (optional)`: the schema and `/synapse-status`'s own query both match this
+exact heading text, and a suffixed one is invisible to both.
+
+`## References` is a plain list of every `[[wikilink]]` already used somewhere else in the body —
+not a new link, a mirror of ones already there, so a reader can see everything the note points to
+in one place instead of re-reading 500+ words of prose to find one. Add to it every time a new
+wikilink is added to the body, the same "touch it every time" discipline `## Open Questions`
+already follows above, just additive instead of pruned. Named `References` rather than
+`Links`/`Sources` specifically because the Synapse Graph node format already reserves `## Sources`/
+`## Links` for something unrelated (source files, typed relations) in that other kind of note
+sharing the same vault.
 
 Any string scalar that is all digits (e.g. a numeric-looking title) must be quoted: an
 unquoted all-digit value is parsed as an integer, which fails a `type: string` schema

package/commands/synapse-note.md

@@ -196,8 +196,17 @@ or supplied directly by a caller like `/synapse-task-note`):
    ## Summary
 
    {essential content}
+
+   ## References
+
+   - [[Wikilink]] mentioned above
    ```
 
+   `## References` is optional — omit it entirely on a note with no wikilinks yet rather than
+   leaving it as an empty heading. Add it (or add to it) the moment the note's first `[[wikilink]]`
+   is written, and keep it a plain mirror of every wikilink already used elsewhere in the body —
+   not a place to introduce a new one.
+
    **Task mode:**
    ```
    ---

package/commands/synapse-task-note.md

@@ -83,10 +83,26 @@ duplicate that scaffolding here, just supply its inputs:
 - **Body:** the checklist from "Compiling the checklist" above, under the single top-level heading —
   exactly the structure `synapse-task`'s "Task file structure" requires (no `## Step` sub-headings).
 - **`## Notes` (pre-implementation):** populate per `synapse-task`'s own convention —
-  - Design reference: `[[{design note title}]]`
   - Key constraints the implementor must not miss
   - Deliberate exclusions (from step 4 above) and why
 
+  No separate "Design reference" bullet here — `## Linking forward` below already puts that pointer
+  right after the task note's own title, not buried after the checklist.
+
+## Linking forward
+
+Immediately after creation, patch the new task note: add `> Design note: [[{design note title}]]`
+right after its own `# {title}` heading, before the lead description:
+
+```
+printf '> Design note: [[%s]]\n\n' "{design note title}" | \
+  synapse vault-patch "{task note path}" --heading "{task note title}" --prepend
+```
+
+The task note's mirror of `## Linking back` below — a compiled task's design is now visible in the
+first line, the same way the design note's own compiled-task backlink already is, instead of
+requiring a scroll past the whole checklist to find it.
+
 ## Linking back
 
 After creation, patch the design note: add `> Compiled task: [[{task note title}]]` near the top —
@@ -134,7 +150,8 @@ Claude: [reads designs/{project}/Rollup direct storage.md, Status: Ready]
         Project already known: {PROJECT} → {prefix}-005.
 
         Created: tasks/{project}/Rollup direct storage implementation.md (task_id: {prefix}-005)
-        Linked back from designs/{project}/Rollup direct storage.md.
+        Linked forward to the design note, and linked back from
+        designs/{project}/Rollup direct storage.md.
 
         Status transitions happen automatically via the synapse-task skill once you start work.
 ```

package/harness/codex/skills/synapse-design-note/SKILL.md

@@ -212,12 +212,24 @@ Discussing | Ready | Reference
 
 ## Open Questions
 - {Anything deferred or unresolved}
+
+## References
+- [[Wikilink]] mentioned above
 ```
 
-`### Alternatives considered` and `## Open Questions` are both optional per the schema — omit
-either section entirely rather than leaving it as an empty heading, and never write it as `##
-Open Questions (optional)`: the schema and `/synapse-status`'s own query both match this exact
-heading text, and a suffixed one is invisible to both.
+`### Alternatives considered`, `## Open Questions`, and `## References` are all optional per the
+schema — omit any of them entirely rather than leaving it as an empty heading, and never write one
+as `## Open Questions (optional)`: the schema and `/synapse-status`'s own query both match this
+exact heading text, and a suffixed one is invisible to both.
+
+`## References` is a plain list of every `[[wikilink]]` already used somewhere else in the body —
+not a new link, a mirror of ones already there, so a reader can see everything the note points to
+in one place instead of re-reading 500+ words of prose to find one. Add to it every time a new
+wikilink is added to the body, the same "touch it every time" discipline `## Open Questions`
+already follows above, just additive instead of pruned. Named `References` rather than
+`Links`/`Sources` specifically because the Synapse Graph node format already reserves `## Sources`/
+`## Links` for something unrelated (source files, typed relations) in that other kind of note
+sharing the same vault.
 
 Resolve tags through the `synapse-vault` skill's configured vocabulary procedure. Fetch machine
 local time once (`synapse now`) — never infer it — and use the exact same value for `created` and

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

@@ -214,8 +214,17 @@ or supplied directly by a caller like the synapse-task-note skill):
    ## Summary
 
    {essential content}
+
+   ## References
+
+   - [[Wikilink]] mentioned above
    ```
 
+   `## References` is optional — omit it entirely on a note with no wikilinks yet rather than
+   leaving it as an empty heading. Add it (or add to it) the moment the note's first `[[wikilink]]`
+   is written, and keep it a plain mirror of every wikilink already used elsewhere in the body —
+   not a place to introduce a new one.
+
    **Task mode:**
    ```
    ---

package/harness/codex/skills/synapse-task-note/SKILL.md

@@ -84,10 +84,26 @@ don't duplicate that scaffolding here, just supply its inputs:
   exactly the structure the synapse-task skill's "Task file structure" requires (no `## Step`
   sub-headings).
 - **`## Notes` (pre-implementation):** populate per the synapse-task skill's own convention —
-  - Design reference: `[[{design note title}]]`
   - Key constraints the implementor must not miss
   - Deliberate exclusions (from step 4 above) and why
 
+  No separate "Design reference" bullet here — `## Linking forward` below already puts that pointer
+  right after the task note's own title, not buried after the checklist.
+
+## Linking forward
+
+Immediately after creation, patch the new task note: add `> Design note: [[{design note title}]]`
+right after its own `# {title}` heading, before the lead description:
+
+```
+printf '> Design note: [[%s]]\n\n' "{design note title}" | \
+  synapse vault-patch "{task note path}" --heading "{task note title}" --prepend
+```
+
+The task note's mirror of `## Linking back` below — a compiled task's design is now visible in the
+first line, the same way the design note's own compiled-task backlink already is, instead of
+requiring a scroll past the whole checklist to find it.
+
 ## Linking back
 
 After creation, patch the design note: add `> Compiled task: [[{task note title}]]` near the top —
@@ -135,7 +151,8 @@ Codex: [reads designs/{project}/Rollup direct storage.md, Status: Ready]
        Project already known: {PROJECT} → {prefix}-005.
 
        Created: tasks/{project}/Rollup direct storage implementation.md (task_id: {prefix}-005)
-       Linked back from designs/{project}/Rollup direct storage.md.
+       Linked forward to the design note, and linked back from
+       designs/{project}/Rollup direct storage.md.
 
        Status transitions happen automatically via the synapse-task skill once you start work.
 ```

package/package.json

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

package/schema/vault-design-note/v1.yaml

@@ -47,6 +47,7 @@ body:
     - type: blockquote
       required: false
       position: immediately_after_h1
+      marker: '> Compiled task:'
       pattern: '^> Compiled task: \[\[[^\]]+\]\]$'
   sections:
     - title: Status
@@ -76,6 +77,10 @@ body:
       level: 2
       required: false
       non_empty: true
+    - title: References
+      level: 2
+      required: false
+      non_empty: true
   section_order: relative
 
 checks:
@@ -110,7 +115,8 @@ lints:
   - no_hard_wrap:
       var: body.prose
     severity: warn
-  - no_id_prefix_in_title:
-      - var: frontmatter.title
-      - var: frontmatter.note_id
+  - not:
+      starts_with:
+        - var: frontmatter.title
+        - var: frontmatter.note_id
     severity: warn

package/schema/vault-note/v1.yaml

@@ -46,7 +46,7 @@ body:
     - title: Details
       level: 2
       required: false
-    - title: Sources
+    - title: References
       level: 2
       required: false
     - title: Open Questions

package/schema/vault-task-note/v1.yaml

@@ -47,6 +47,12 @@ body:
     required: true
     count: 1
     equals: frontmatter.title
+  preamble:
+    - type: blockquote
+      required: false
+      position: immediately_after_h1
+      marker: '> Design note:'
+      pattern: '^> Design note: \[\[[^\]]+\]\]$'
   lead:
     type: prose
     required: true
@@ -109,7 +115,8 @@ lints:
   - no_hard_wrap:
       var: body.prose
     severity: warn
-  - no_id_prefix_in_title:
-      - var: frontmatter.title
-      - var: frontmatter.task_id
+  - not:
+      starts_with:
+        - var: frontmatter.title
+        - var: frontmatter.task_id
     severity: warn