@imunitic/synapse 0.3.2 → 0.4.0

package/bin/synapse-hook.cjs

@@ -7,6 +7,7 @@
 "use strict";
 
 const { spawnSync } = require("child_process");
+const path = require("path");
 const { hookPath, platformPackageName } = require("../lib/resolve-binaries.cjs");
 
 const bin = hookPath();
@@ -15,5 +16,7 @@ if (!bin) {
   process.exit(1);
 }
 
-const result = spawnSync(bin, process.argv.slice(2), { stdio: "inherit" });
+const env = { ...process.env };
+if (!env.SYNAPSE_CONTENT_ROOT) env.SYNAPSE_CONTENT_ROOT = path.join(__dirname, "..");
+const result = spawnSync(bin, process.argv.slice(2), { stdio: "inherit", env });
 process.exit(result.status ?? 1);

package/bin/synapse.cjs

@@ -8,6 +8,7 @@
 "use strict";
 
 const { spawnSync } = require("child_process");
+const path = require("path");
 const { cliPath, platformPackageName } = require("../lib/resolve-binaries.cjs");
 
 const bin = cliPath();
@@ -16,5 +17,7 @@ if (!bin) {
   process.exit(1);
 }
 
-const result = spawnSync(bin, process.argv.slice(2), { stdio: "inherit" });
+const env = { ...process.env };
+if (!env.SYNAPSE_CONTENT_ROOT) env.SYNAPSE_CONTENT_ROOT = path.join(__dirname, "..");
+const result = spawnSync(bin, process.argv.slice(2), { stdio: "inherit", env });
 process.exit(result.status ?? 1);

package/commands/synapse-design-note.md

@@ -177,10 +177,13 @@ so the `## Status` line is the only lifecycle marker that matters. It simply sta
 
 ```
 ---
+schema: vault-design-note/v1
 title: "{PROJECT} — {Topic}"
 project: {prefix}
-created: "{now}"
 note_id: {id}
+created: "{now}"
+updated: "{now}"
+tags: [{comma-separated configured tags, or empty}]
 ---
 
 # {PROJECT} — {Topic}
@@ -204,7 +207,13 @@ Discussing | Ready | Reference
 - {Anything deferred or unresolved}
 ```
 
-Fetch machine local time for `created` (`date '+%Y-%m-%d %H:%M'`) — never infer it.
+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
+field. `title`, `project`, `note_id`, and both timestamps are quoted above.
+
+Resolve tags through the `synapse-vault` skill's configured vocabulary procedure. Fetch machine
+local time once (`date '+%Y-%m-%d %H:%M:%S %Z'`) — never infer it — and use the exact same value
+for `created` and `updated`.
 
 No `Notes`/changelog section — it stays a small, single-conclusion note; there's no long-running
 edit history here worth tracking separately.

package/commands/synapse-note.md

@@ -171,36 +171,64 @@ or supplied directly by a caller like `/synapse-task-note`):
    characters (`/ : * ? " < > |`) with `-`, collapse repeated whitespace.
    No timestamp prefix, no project-slug prefix — the filename is just the
    (sanitized) title.
-2. Fetch machine local time: `date '+%Y-%m-%d %H:%M'` — never use inferred
-   time. Use this for the `created` frontmatter field.
-3. Build the file content:
+2. Resolve tags through the `synapse-vault` skill's configured
+   `synapse-tag-vocabulary.conf` procedure. Choose only entries already in that vocabulary; an
+   empty list is valid when no tag applies, but the `tags` field itself is mandatory.
+3. Fetch machine local time once: `date '+%Y-%m-%d %H:%M:%S %Z'` — never use inferred
+   time. Use the exact same value for `created` and `updated`.
+4. Build the file content. A bare note needs a concise Summary. A task note needs lead prose and
+   at least one real flat checklist item before it can be written; never create an invalid empty
+   skeleton and promise to populate it later.
 
    **Bare mode:**
    ```
    ---
+   schema: vault-note/v1
    title: "{title}"
-   created: "{now}"
    note_id: {id}
+   created: "{now}"
+   updated: "{now}"
+   tags: [{comma-separated tags, or empty}]
    ---
 
+   # {title}
+
+   ## Summary
+
+   {essential content}
    ```
 
    **Task mode:**
    ```
    ---
+   schema: vault-task-note/v1
    title: "{title}"
-   created: "{now}"
+   project: {prefix}
    task_id: {task-id}
+   created: "{now}"
+   updated: "{now}"
+   tags: [{comma-separated tags, or empty}]
    status: TODO
-   last_updated: "{now}"
    ---
 
    # {title}
 
+   {task description}
+
+   ## Checklist
+
+   - [ ] {first implementation step}
+
    ## Notes
 
+   {constraints or context}
    ```
-4. Write it with `synapse vault-write <path>` (content on stdin). Task mode: path
+
+   Quote every scalar string value. In particular, a value that is all digits
+   (a numeric-looking `title`, or any future numeric id) must be quoted — an
+   unquoted all-digit value is parsed as an integer and fails a `type: string`
+   schema field.
+5. Write it with `synapse vault-write <path>` (content on stdin). Task mode: path
    `tasks/{project}/{filename}.md` (project resolved in "Resolving the
    project folder" above). Bare mode: path `{category}/{filename}.md`
    (category resolved above).
@@ -209,7 +237,6 @@ or supplied directly by a caller like `/synapse-task-note`):
 
 Report the file path back to the user.
 
-- Bare mode: note that the note is intentionally near-empty.
+- Bare mode: report the Summary that was captured.
 - Task mode: note the task ID extracted or resolved, and remind the user
-  to populate the `## Notes` section and checklist before starting work,
-  per the `synapse-task` skill.
+  that future status transitions are managed by the `synapse-task` skill.

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

@@ -178,9 +178,13 @@ so the `## Status` line is the only lifecycle marker that matters. It simply sta
 
 ```
 ---
+schema: vault-design-note/v1
 title: "{PROJECT} — {Topic}"
 project: {prefix}
+note_id: {id}
 created: "{now}"
+updated: "{now}"
+tags: [{comma-separated configured tags, or empty}]
 ---
 
 # {PROJECT} — {Topic}
@@ -204,7 +208,9 @@ Discussing | Ready | Reference
 - {Anything deferred or unresolved}
 ```
 
-Fetch machine local time for `created` (`date '+%Y-%m-%d %H:%M'`) — never infer it.
+Resolve tags through the `synapse-vault` skill's configured vocabulary procedure. Fetch machine
+local time once (`date '+%Y-%m-%d %H:%M:%S %Z'`) — never infer it — and use the exact same value
+for `created` and `updated`.
 
 No `Notes`/changelog section — it stays a small, single-conclusion note; there's no long-running
 edit history here worth tracking separately.

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

@@ -189,36 +189,58 @@ or supplied directly by a caller like the synapse-task-note skill):
    characters (`/ : * ? " < > |`) with `-`, collapse repeated whitespace.
    No timestamp prefix, no project-slug prefix — the filename is just the
    (sanitized) title.
-2. Fetch machine local time: `date '+%Y-%m-%d %H:%M'` — never use inferred
-   time. Use this for the `created` frontmatter field.
-3. Build the file content:
+2. Resolve tags through the `synapse-vault` skill's configured
+   `synapse-tag-vocabulary.conf` procedure. Choose only configured entries; an empty list is valid
+   when no tag applies, but the field itself is mandatory.
+3. Fetch machine local time once: `date '+%Y-%m-%d %H:%M:%S %Z'` — never use inferred
+   time. Use the exact same value for `created` and `updated`.
+4. Build the file content. Bare notes require a concise Summary. Task notes require lead prose and
+   at least one real flat checklist item before the first write.
 
    **Bare mode:**
    ```
    ---
+   schema: vault-note/v1
    title: "{title}"
-   created: "{now}"
    note_id: {id}
+   created: "{now}"
+   updated: "{now}"
+   tags: [{comma-separated tags, or empty}]
    ---
 
+   # {title}
+
+   ## Summary
+
+   {essential content}
    ```
 
    **Task mode:**
    ```
    ---
+   schema: vault-task-note/v1
    title: "{title}"
-   created: "{now}"
+   project: {prefix}
    task_id: {task-id}
+   created: "{now}"
+   updated: "{now}"
+   tags: [{comma-separated tags, or empty}]
    status: TODO
-   last_updated: "{now}"
    ---
 
    # {title}
 
+   {task description}
+
+   ## Checklist
+
+   - [ ] {first implementation step}
+
    ## Notes
 
+   {constraints or context}
    ```
-4. Write it with `synapse vault-write <path>` (content on stdin). Task mode: path
+5. Write it with `synapse vault-write <path>` (content on stdin). Task mode: path
    `tasks/{project}/{filename}.md` (project resolved in "Resolving the
    project folder" above). Bare mode: path `{category}/{filename}.md`
    (category resolved above).
@@ -227,7 +249,6 @@ or supplied directly by a caller like the synapse-task-note skill):
 
 Report the file path back to the user.
 
-- Bare mode: note that the note is intentionally near-empty.
+- Bare mode: report the Summary that was captured.
 - Task mode: note the task ID extracted or resolved, and remind the user
-  to populate the `## Notes` section and checklist before starting work,
-  per the `synapse-task` skill.
+  that future status transitions are managed by the `synapse-task` skill.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imunitic/synapse",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "Memory for Claude Code, Codex CLI, and OpenCode: a durable Obsidian vault plus a per-repo code graph.",
   "repository": {
     "type": "git",
@@ -17,14 +17,15 @@
     "skills",
     "commands",
     "harness",
+    "schema",
     "synapse-claude.md",
     "Index.md.template",
     "*.conf.template"
   ],
   "optionalDependencies": {
-    "@imunitic/synapse-darwin-arm64": "0.3.2",
-    "@imunitic/synapse-linux-x64": "0.3.2",
-    "@imunitic/synapse-linux-arm64": "0.3.2"
+    "@imunitic/synapse-darwin-arm64": "0.4.0",
+    "@imunitic/synapse-linux-x64": "0.4.0",
+    "@imunitic/synapse-linux-arm64": "0.4.0"
   },
   "license": "SEE LICENSE IN LICENSE"
 }

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

@@ -0,0 +1,95 @@
+# Declared keys are the full v1 spec; enforcement is a deliberate subset — unknown note fields are ignored, never an error.
+schema: synapse-note-schema/v1
+id: vault-design-note/v1
+
+frontmatter:
+  fields:
+    schema:
+      type: string
+      required: true
+      const: vault-design-note/v1
+    title:
+      type: string
+      required: true
+      min_length: 1
+    project:
+      type: string
+      required: true
+      min_length: 1
+    note_id:
+      type: string
+      required: true
+      pattern: '^[a-z][a-z0-9-]*-[0-9]{3,}$'
+      mutable: false
+    created:
+      type: timestamp
+      required: true
+      format: 'YYYY-MM-dd HH:mm:ss TZ'
+      timezone: local
+      mutable: false
+    updated:
+      type: timestamp
+      required: true
+      format: 'YYYY-MM-dd HH:mm:ss TZ'
+      timezone: local
+      update_on: [vault-write, vault-patch]
+    tags:
+      type: list
+      required: true
+      items: string
+
+body:
+  h1:
+    required: true
+    count: 1
+    equals: frontmatter.title
+  preamble:
+    - type: blockquote
+      required: false
+      position: immediately_after_h1
+      pattern: '^> Compiled task: \[\[[^\]]+\]\]$'
+  sections:
+    - title: Status
+      level: 2
+      required: true
+      content:
+        type: string
+        enum: [Discussing, Ready, Reference]
+    - title: Problem
+      level: 2
+      required: true
+      non_empty: true
+    - title: Approach
+      level: 2
+      required: true
+      non_empty: true
+      children:
+        - title: Alternatives considered
+          level: 3
+          required: false
+          non_empty: true
+    - title: Constraints
+      level: 2
+      required: true
+      non_empty: true
+    - title: Open Questions
+      level: 2
+      required: false
+      non_empty: true
+  section_order: relative
+
+checks:
+  - equals: [filename.stem, frontmatter.title]
+  - unique: frontmatter.note_id
+    when: create
+  - vocabulary:
+      field: frontmatter.project
+      source: synapse-projects.conf
+      projection: values
+  - vocabulary:
+      field: frontmatter.tags
+      source: synapse-tag-vocabulary.conf
+  - not_before: [frontmatter.updated, frontmatter.created]
+  - equals:
+      values: [frontmatter.created, frontmatter.updated]
+      when: create

package/schema/vault-note/v1.yaml

@@ -0,0 +1,67 @@
+# Declared keys are the full v1 spec; enforcement is a deliberate subset — unknown note fields are ignored, never an error.
+schema: synapse-note-schema/v1
+id: vault-note/v1
+
+frontmatter:
+  fields:
+    schema:
+      type: string
+      required: true
+      const: vault-note/v1
+    title:
+      type: string
+      required: true
+      min_length: 1
+    note_id:
+      type: string
+      required: true
+      pattern: '^[a-z][a-z0-9-]*-[0-9]{3,}$'
+      mutable: false
+    created:
+      type: timestamp
+      required: true
+      format: 'YYYY-MM-dd HH:mm:ss TZ'
+      timezone: local
+      mutable: false
+    updated:
+      type: timestamp
+      required: true
+      format: 'YYYY-MM-dd HH:mm:ss TZ'
+      timezone: local
+      update_on: [vault-write, vault-patch]
+    tags:
+      type: list
+      required: true
+      items: string
+
+body:
+  h1:
+    required: true
+    count: 1
+    equals: frontmatter.title
+  sections:
+    - title: Summary
+      level: 2
+      required: true
+    - title: Details
+      level: 2
+      required: false
+    - title: Sources
+      level: 2
+      required: false
+    - title: Open Questions
+      level: 2
+      required: false
+  section_order: relative
+
+checks:
+  - equals: [filename.stem, frontmatter.title]
+  - unique: frontmatter.note_id
+    when: create
+  - vocabulary:
+      field: frontmatter.tags
+      source: synapse-tag-vocabulary.conf
+  - not_before: [frontmatter.updated, frontmatter.created]
+  - equals:
+      values: [frontmatter.created, frontmatter.updated]
+      when: create

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

@@ -0,0 +1,93 @@
+# Declared keys are the full v1 spec; enforcement is a deliberate subset — unknown note fields are ignored, never an error.
+schema: synapse-note-schema/v1
+id: vault-task-note/v1
+
+frontmatter:
+  fields:
+    schema:
+      type: string
+      required: true
+      const: vault-task-note/v1
+    title:
+      type: string
+      required: true
+      min_length: 1
+    project:
+      type: string
+      required: true
+      min_length: 1
+    task_id:
+      type: string
+      required: true
+      pattern: '^[a-z][a-z0-9-]*-[0-9]{3,}$'
+      mutable: false
+    created:
+      type: timestamp
+      required: true
+      format: 'YYYY-MM-dd HH:mm:ss TZ'
+      timezone: local
+      mutable: false
+    updated:
+      type: timestamp
+      required: true
+      format: 'YYYY-MM-dd HH:mm:ss TZ'
+      timezone: local
+      update_on: [vault-write, vault-patch]
+    tags:
+      type: list
+      required: true
+      items: string
+    status:
+      type: string
+      required: true
+      enum: [TODO, IN-PROGRESS, REVIEW, DONE, CANCELED]
+
+body:
+  h1:
+    required: true
+    count: 1
+    equals: frontmatter.title
+  lead:
+    type: prose
+    required: true
+    position: before_sections
+  checklist:
+    required: true
+    min_items: 1
+    position: before_sections
+    nested_items: false
+    allowed_children: [paragraph, fenced_code]
+  sections:
+    - title: Checklist
+      level: 2
+      required: true
+    - title: Notes
+      level: 2
+      required: false
+      max_occurs: 1
+      children:
+        - level: 3
+          required: false
+          repeatable: true
+          title_pattern: '^[0-9]{4}-[0-9]{2}-[0-9]{2} — .+$'
+  section_order: relative
+
+checks:
+  - equals: [filename.stem, frontmatter.title]
+  - unique: frontmatter.task_id
+    when: create
+  - vocabulary:
+      field: frontmatter.project
+      source: synapse-projects.conf
+      projection: values
+  - vocabulary:
+      field: frontmatter.tags
+      source: synapse-tag-vocabulary.conf
+  - not_before: [frontmatter.updated, frontmatter.created]
+  - equals:
+      values: [frontmatter.created, frontmatter.updated]
+      when: create
+  - const:
+      field: frontmatter.status
+      value: TODO
+      when: create

package/skills/synapse-task/SKILL.md

@@ -21,12 +21,12 @@ Invoke this skill **automatically** in two situations:
 
 1. **Starting work on a task** — as soon as the user confirms work is
    beginning, before writing any code. Set `status: IN-PROGRESS` and update
-   `last_updated`. No notes needed at this point.
+   `updated`. No notes needed at this point.
 
 2. **Finishing work on a task** — after all phases are committed and
    the task note's checklist has been updated. Set `status: REVIEW` (if all
    items checked) or `status: IN-PROGRESS` (if any remain), update
-   `last_updated`, and append an implementation summary to the `## Notes`
+   `updated`, and append an implementation summary to the `## Notes`
    section.
 
 Never wait to be asked — apply this skill proactively at both transitions.
@@ -35,7 +35,7 @@ Never wait to be asked — apply this skill proactively at both transitions.
 
 - Updates the `status:` frontmatter field (`TODO` → `IN-PROGRESS` or
   `REVIEW`).
-- Updates `last_updated` in frontmatter.
+- Updates `updated` in frontmatter.
 - At task completion: appends concise implementation bullets to the
   existing `## Notes` section (or creates one if none exists).
 
@@ -60,11 +60,11 @@ into `status:` either — always go through this skill, which caps at
 2. Inspect its checklist items (`- [ ]` / `- [x]`).
 3. Determine the new `status:` value: `IN-PROGRESS` if any unchecked,
    `REVIEW` if all checked.
-4. Fetch machine local time: `date '+%Y-%m-%d %H:%M'` — never use inferred
+4. Fetch machine local time: `date '+%Y-%m-%d %H:%M:%S %Z'` — never use inferred
    time.
-5. Update `status:` and `last_updated:` with two `synapse frontmatter set`
+5. Update `status:` and `updated:` with two `synapse frontmatter set`
    calls, one per field: `synapse frontmatter set <path> status <value>`
-   then `synapse frontmatter set <path> last_updated "{now}"`. Each call
+   then `synapse frontmatter set <path> updated "{now}"`. Each call
    changes exactly that one line and nothing else, entirely inside the
    compiled binary — the note's body never enters your context at all.
    When the command isn't available, fall back to **read-modify-write**:
@@ -94,12 +94,14 @@ The vault-patch hazards below are the task-note-specific instance of a general r
 `synapse-vault` skill carries the full list (H1 replace, nested heading paths, frontmatter) for
 every note, not just task notes.
 
-**Do not use `vault-patch --heading "{H1 title}" --replace` to edit checklist items.** A top-level
-heading's own section extends through *all* nested subheadings (including `## Notes`), not just
-the leading paragraph/checklist directly under it — a replace there silently deletes everything
-past the checklist, including the Notes section. To check off checklist items,
-instead `synapse vault-read` the full file, edit the `- [ ]` → `- [x]` lines in the
-returned content, and `synapse vault-write` the whole file back.
+**Edit checklist items through the `Checklist` heading, never the H1.** With `## Checklist` as its
+own H2 — a sibling of `## Notes` — `vault-patch --heading "{H1 title}::Checklist" --replace`
+(supplying the full new checklist) is the correct tool for a whole-checklist edit and leaves
+`## Notes` untouched. Never target the top-level H1 (`--heading "{H1 title}"`): its section extends
+through *all* nested subheadings (including `## Notes`), so a replace there silently deletes
+everything past the checklist. To flip a single `- [ ]` → `- [x]` in place, `synapse vault-read`
+the full file, edit that one line, and `synapse vault-write` the whole file back — there is no
+per-item toggle yet.
 
 ## Notes format
 
@@ -116,18 +118,26 @@ level. Append to the last existing notes section.
 ## Task file structure
 
 Each task note, in any project, has **exactly one top-level heading** (the
-task itself, `# {title}`). Implementation steps go as `- [ ]` checklist items
-**under that heading**, not as additional headings. Do not create `##
-Step` sub-headings for implementation steps.
+task itself, `# {title}`). Under it: lead prose describing the task, then a
+required `## Checklist` heading holding the `- [ ]` implementation items,
+then a `## Notes` section. Do not create `## Step` sub-headings for
+implementation steps, and do not put checklist items directly under the H1.
 
 Correct structure:
 ```md
 # Implement something
 
 Description of the task.
+
+## Checklist
+
 - [ ] Step one
 - [ ] Step two
 - [ ] Step three
+
+## Notes
+
+{constraints or context}
 ```
 
 Wrong structure (do not do this):