@imunitic/synapse 0.3.1 → 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

@@ -32,8 +32,9 @@ below:
 The title is whatever the user is naming or describing, minus any mode-signaling phrasing. Example:
 
 - "make a note about my idea" → bare note titled "My idea"
-- "track this as a task: implement Foo" → task note titled "Implement Foo" (before task-ID
-  resolution prepends the resolved ID, per "Resolving a missing task ID" below)
+- "track this as a task: implement Foo" → task note titled "Implement Foo"; if no task ID is
+  already present in that phrasing, "Resolving a missing task ID" below assigns one to `task_id`
+  in frontmatter only, without changing the title
 
 In task mode, also attempt to extract a task ID from the title by matching a `{prefix}-\d+` pattern
 (letters, a hyphen, then digits) — the user sometimes already names one directly (e.g. "track
@@ -105,19 +106,19 @@ unchanged for anyone who has never touched an XDG config directory.
 5. Whenever step 3 or step 4 resolves a pair not already in the conf file (including a fresh
    `project-name=prefix` line matching what was just deduced or asked), append it — so the next task
    for this project resolves from step 2 without a search or a question.
-6. Once the prefix is known, find the next number: run `synapse vault-search --fields
-   frontmatter.task_id` with `{"var": "frontmatter.task_id"}` on stdin,
-   filter the returned values client-side for ones matching
-   `{prefix}-\d+`, take the highest number found, add 1. If none exist yet
-   for that prefix, start at 1.
+6. Once the prefix is known, find the next number. `task_id` and `note_id` (the id every note gets
+   — see "Assigning a note_id" below) share one counter per prefix, so this has to check both
+   fields, not just `task_id` alone: run `synapse vault-search --fields
+   frontmatter.task_id,frontmatter.note_id` with `{"or": [{"!=": [{"var": "frontmatter.task_id"},
+   null]}, {"!=": [{"var": "frontmatter.note_id"}, null]}]}` on stdin, filter both returned columns
+   client-side for values matching `{prefix}-\d+`, take the highest number found across both, add
+   1. If none exist yet for that prefix, start at 1.
 7. Format the new task ID **zero-padded to 3 digits** (`{prefix}-001`, `{prefix}-030`,
    `{prefix}-037`, ...), matching the org-roam-era convention — widening
    naturally past 3 digits if a prefix ever needs it.
-8. **Prepend the resolved task ID to the title itself** — the final title
-   becomes `{task-id} — {original title}` (em dash). Use this same final
-   title for both the `title` frontmatter field and the `# ` heading, and
-   use the resolved task ID for `task_id`. Don't let the frontmatter task
-   ID and the visible title disagree.
+8. **The title itself is never prefixed with the task ID.** `task_id` lives in frontmatter only —
+   the same convention `note_id` already uses for bare and design notes, now consistent across all
+   three kinds. `title`, the `# ` heading, and the filename all stay exactly the given topic.
 
 The synapse-design-note and synapse-task-note skills read the same conf file directly for the same
 reason — they don't duplicate this resolution logic, just this file.
@@ -146,6 +147,25 @@ triage/priority one a vault owner might maintain by hand (e.g.
 sorting a note into one of those, if a category has one, is never an
 agent's call to make.
 
+## Assigning a note_id (bare mode only)
+
+Task mode already gets its id via "Resolving a missing task ID" above. Bare mode needs one too —
+every note gets a `note_id`, not just tasks — but unlike task mode, this step never blocks with a
+question: a quick bare note shouldn't require an interrupt just to get an id.
+
+1. Try steps 1-3 of "Resolving a missing task ID" above (repo context, the resolved
+   `synapse-projects.conf`, then deducing from the vault itself) to resolve a project prefix. Skip
+   step 4 entirely — if none of the first three resolve one, fall through to step 2 below instead of
+   asking.
+2. If a prefix resolved: mint the next number the same shared-counter way as that section's step 6
+   (checking both `task_id` and `note_id` across the vault for that prefix). If no prefix resolved:
+   mint `note-NNN` instead — its own flat, project-less counter, found the same way (`synapse
+   vault-search --fields frontmatter.note_id`, filter for `note-\d+`, take the highest, add 1; start
+   at 1 if none exist yet).
+3. Carry the resolved `{id}` into "Creating the note" below as `note_id`. Unlike task mode, the title
+   itself is untouched — no id prefix on the visible title or the `title` frontmatter field for a bare
+   note.
+
 ## Resolving the project folder (task mode only)
 
 Task notes are grouped one level deeper by project, `tasks/{project}/{filename}.md` — see the
@@ -169,35 +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}"
+   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).
@@ -206,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/harness/codex/skills/synapse-task-note/SKILL.md

@@ -68,8 +68,9 @@ Follow the synapse-note skill's task-mode procedure exactly (its "Creating the n
 don't duplicate that scaffolding here, just supply its inputs:
 
 - **Title:** a short, plain description of the compiled plan (e.g. "Rollup direct storage
-  implementation") — the synapse-note skill's task mode resolves the project prefix and `task_id`
-  and prepends them itself.
+  implementation") — stays exactly this, never prefixed with the resolved `task_id`; the
+  synapse-note skill's task mode resolves the project prefix and `task_id` itself and puts them in
+  frontmatter only.
 - **Project:** derive from the source design note's `project:` frontmatter — that prefix is already
   resolved (the design note went through the synapse-design-note skill's resolution when it was
   created, which reads/appends the resolved `synapse-projects.conf`, per the synapse-note skill's
@@ -133,7 +134,7 @@ Codex: [reads designs/{PROJECT} — Rollup direct storage.md, Status: Ready]
 
        Project already known: {PROJECT} → {prefix}-005.
 
-       Created: tasks/{PROJECT}/{prefix}-005 — Rollup direct storage implementation.md
+       Created: tasks/{PROJECT}/Rollup direct storage implementation.md (task_id: {prefix}-005)
        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.3.1",
+  "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.1",
-    "@imunitic/synapse-linux-x64": "0.3.1",
-    "@imunitic/synapse-linux-arm64": "0.3.1"
+    "@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):