syntaur 0.8.0 → 0.12.0

package/platforms/codex/skills/plan-assignment/SKILL.md

@@ -99,28 +99,49 @@ Body sections:
 
 If the target file already exists (only possible for `plan.md` on first re-run against a scaffolded-but-empty plan), preserve the frontmatter and replace only the body, flipping `status` from `draft` to `in_progress` and updating `updated`.
 
-### 5c. Update assignment.md Todos
+### 5c. Update assignment.md Todos (four-todo cycle)
 
-Read `<assignmentDir>/assignment.md` and locate the `## Todos` section.
+Read `<assignmentDir>/assignment.md` and locate the `## Todos` section. Per
+the **Create-and-Plan-Assignment** playbook, every plan version uses a
+four-todo cycle: Create / Review / Implement / Review implementation.
 
-1. **Supersede prior plan todos.** For every unchecked line matching `- [ ] Execute [<label>](./plan.md)` or `- [ ] Execute [<label>](./plan-v<N>.md)`, rewrite as:
+1. **Supersede the prior plan's four-todo cycle.** For every line referencing
+   the prior plan file (`./plan.md` or `./plan-v<N-1>.md`) — both the older
+   single-line `Execute [...]` form AND the four-todo-cycle lines (Create /
+   Review / Implement / Review implementation of) — rewrite as:
 
    ```
-   - [x] ~~Execute [<label>](./<old-plan-filename>)~~ (superseded by <versionLabel>)
+   - [x] ~~<original line body>~~ (superseded by <versionLabel>)
    ```
 
-   Never delete the old line — preserve history.
+   Mark the checkbox `[x]` and wrap the body in `~~...~~`. Never delete any
+   prior todo — preserve history.
 
-2. **Append the new plan todo.** Add a new line to the end of `## Todos`:
+2. **Append the new four-todo cycle.** Add four lines to the end of
+   `## Todos`, replacing `<versionLabel>` with the human label (e.g.
+   `plan v2`) and `<planFilename>` with the new file (e.g. `plan-v2.md`):
 
    ```
-   - [ ] Execute [<versionLabel>](./<planFilename>)
+   - [ ] Create [<versionLabel>](./<planFilename>)
+   - [ ] Review [<versionLabel>](./<planFilename>)
+   - [ ] Implement [<versionLabel>](./<planFilename>)
+   - [ ] Review implementation of [<versionLabel>](./<planFilename>)
    ```
 
-3. **Missing-section fallback.** If `## Todos` does not exist (legacy assignment predating this convention), insert it immediately after `## Acceptance Criteria` with a short guidance HTML comment followed by the new todo line.
+   For the first plan ever (`plan.md`), the label is `plan` and the four todos
+   point at `./plan.md`.
+
+3. **Missing-section fallback.** If `## Todos` does not exist (legacy
+   assignment predating this convention), insert it immediately after
+   `## Acceptance Criteria` with a short guidance HTML comment followed by
+   the new four-todo cycle.
 
 Also refresh the assignment frontmatter `updated` timestamp.
 
+> **Note:** the `syntaur plan version` CLI verb (used by the `replan` skill)
+> applies this exact same four-todo-cycle supersede pattern — `plan-assignment`
+> and `replan` are now in lockstep on this convention.
+
 ## Step 6: Report to User
 
 After writing the plan:

package/platforms/codex/skills/replan/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: replan
+description: >-
+  Create a new versioned plan (`plan-v<N>.md`) for the active Syntaur
+  assignment after the current plan has been implemented (or a major scope
+  shift makes editing the existing plan misleading). Use when the user wants to
+  "create plan-v2", "replan", "version the plan", "make a new plan revision",
+  or when work needs another round under the Plan Versioning playbook.
+license: MIT
+metadata:
+  author: prong-horn
+  version: "1.0.0"
+---
+
+# Replan
+
+Bump the active assignment to a new plan version (`plan.md` → `plan-v2.md`,
+`plan-v2.md` → `plan-v3.md`, …). The CLI does the deterministic file ops; this
+skill writes the **body** of the new plan.
+
+This skill follows the **Plan Versioning** and **Create-and-Plan-Assignment**
+playbooks: prior plan-cycle todos are marked done with strikethrough +
+`(superseded by plan-v<N>)`, and a fresh four-todo cycle (Create / Review /
+Implement / Review implementation) is appended for the new plan. **Superseded
+todos are never deleted.**
+
+## When NOT to use this skill
+
+- The current plan has not been implemented yet — per the Plan Versioning
+  playbook, iterate on `plan.md` directly while it is still in draft /
+  in_progress.
+- The assignment is in a terminal status (`completed`, `failed`, `cancelled`).
+  Reopen it first via `syntaur reopen`.
+- You only need to add a new task to an in-flight plan — edit the existing
+  plan; do not bump version.
+- You want to write a fresh plan for a different assignment — switch context
+  via `clear-assignment` + `grab-assignment`, then call `plan-assignment`.
+
+## Step 1: Verify there is an active assignment
+
+Read `.syntaur/context.json` from the current working directory. Extract
+`assignmentSlug`, `projectSlug` (may be null for standalone), and
+`assignmentDir`.
+
+If the file is missing or has no `assignmentSlug`, abort with: "No active
+Syntaur assignment. Run `grab-assignment` first." Do not invent values.
+
+## Step 2: Confirm the prior plan was implemented
+
+Read the current plan file (the highest existing `plan*.md`). If its
+`## Tasks` (or equivalent) section still contains unchecked items AND the user
+has not explicitly said the prior plan is done, ask: "The current plan still
+has N unchecked tasks. Are you sure you want to create plan-v<N>? (Plan
+Versioning playbook recommends iterating on `plan.md` until implementation
+is complete.)" Stop unless the user confirms.
+
+## Step 3: Run `syntaur plan version`
+
+```bash
+syntaur plan version --assignment <assignmentSlug> [--project <projectSlug>]
+```
+
+This is the only file-mutating step the skill performs through the CLI. It:
+
+1. Picks the next available `plan-v<N>.md` filename.
+2. Writes a stub plan with frontmatter and a `## Carried-forward tasks`
+   section pre-populated with any unchecked todos from the prior plan body.
+3. Rewrites the assignment.md `## Todos` section per the four-todo cycle:
+   marks the four prior plan-cycle todos as
+   `- [x] ~~<original>~~ (superseded by plan-v<N>)` and appends a fresh
+   `Create / Review / Implement / Review implementation` cycle pointing at the
+   new file.
+4. Never deletes any prior todo.
+
+If the CLI exits non-zero, surface the error to the user and stop.
+
+## Step 4: Read the prior plan and the new stub
+
+Read the prior `plan*.md` and the freshly created `plan-v<N>.md`. The stub
+already contains:
+
+- Frontmatter (`assignment`, `status: draft`, `created`, `updated`)
+- A heading
+- A `## Objective` section with a placeholder
+- A `## Carried-forward tasks` section
+- Empty `## Tasks` and `## Verification` sections
+
+## Step 5: Write the new plan body
+
+Replace the placeholder content in the stub with a concrete, implementable
+plan for the new revision. Match the structure of the prior plan (Files /
+Tasks / Verification, etc.) but keep the body concise. Document explicitly
+**why** a new revision is needed (e.g., "scope expanded after review",
+"rework after partial implementation").
+
+Do NOT touch `assignment.md` here — the CLI already updated `## Todos`.
+
+## Step 6: Update progress.md
+
+Append a progress entry recording the new plan version, the reason, and a
+pointer to the new plan file.
+
+## Step 7: Report to User
+
+Summarize:
+
+- New plan path (`<assignmentDir>/plan-v<N>.md`).
+- Number of carried-forward unchecked tasks.
+- Number of prior todos rewritten as superseded (should be the four-todo
+  cycle of the previous plan).
+- Reminder: prior plan files are kept on disk as immutable history; do not
+  delete them.
+- Next step: review the new plan and begin the new four-todo cycle.

package/platforms/codex/skills/resume-session/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: resume-session
+description: >-
+  Re-orient a fresh Syntaur session on the active assignment without
+  re-reading the full transcript. Loads the latest saved session summary,
+  `.syntaur/context.json`, and any open handoff. Use when the user says
+  "resume", "pick up where we left off", "continue this assignment", or after
+  a compact / new session start. Symmetric counterpart to
+  `/save-session-summary`.
+license: MIT
+metadata:
+  author: prong-horn
+  version: "1.0.0"
+---
+
+# Resume Session
+
+Print a compact orientation block so the agent (and the user) can pick up the
+active assignment cleanly. **Idempotent — does not mutate any state.** Re-run
+freely; nothing on disk changes.
+
+## When NOT to use this skill
+
+- Cross-ticket handoff to a downstream assignment — that's `complete-assignment`
+  (writes `handoff.md`).
+- First-time grab of an assignment — use `/grab-assignment` instead; this skill
+  assumes context already exists.
+- Saving the current session's progress — that's `/save-session-summary` (the
+  symmetric write side).
+
+## Step 1: Verify there is an active context
+
+Run `syntaur session resume`. The CLI:
+
+1. Reads `.syntaur/context.json` from the current working directory.
+2. Aborts (exit 1) with a clear message if missing or if no `assignmentDir`
+   is set — telling the user to run `grab-assignment` first.
+3. Otherwise scans `<assignmentDir>/sessions/<sid>/summary.md` and picks the
+   most recently modified.
+4. Reads `<assignmentDir>/handoff.md` (the canonical single-file handoff per
+   assignment, managed by `complete-assignment`) and reports it if its body
+   has been written beyond the scaffolded placeholder.
+5. Prints a human-readable orientation block (project, assignment, branch,
+   workspace root, latest summary path, open handoff, warnings).
+
+If the CLI prints warnings, surface them — the most common is "no session
+summary on disk", which means a prior session never ran
+`/save-session-summary`.
+
+## Step 2: Read the latest session summary (when present)
+
+Open the path printed in step 1 (`<assignmentDir>/sessions/<sid>/summary.md`)
+and load its `## Snapshot`, `## What Was Done`, `## What's Next`, `## Open
+Questions`, and `## Load-Bearing Context` sections. Use these to seed your
+working knowledge of the assignment without scanning the full transcript.
+
+## Step 3: Read the open handoff (when present)
+
+If the CLI reported an open handoff, read that file too. It is the highest
+priority signal — there is an outstanding baton to consume.
+
+## Step 4: Read assignment.md and progress.md
+
+Always read the current assignment.md (objective, acceptance criteria, todos)
+and the tail of progress.md so you know what has been logged since the last
+summary.
+
+## Step 5: Idempotency check (optional)
+
+Re-run `syntaur session resume --json` if you want machine-readable confirmation
+that nothing on disk changed between runs. The output is deterministic for a
+given on-disk state.
+
+## Step 6: Report to User
+
+Summarize:
+
+- Active project / assignment / branch.
+- Latest session summary timestamp + a one-sentence what's-next pulled from
+  it.
+- Whether there is an open handoff (and a one-line summary if so).
+- Open questions to flag back to the user.
+- Suggested next concrete action.

package/platforms/codex/skills/set-workspace/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: set-workspace
+description: >-
+  Populate the four `workspace.*` fields (repository, worktreePath, branch,
+  parentBranch) in the active assignment's `assignment.md` frontmatter
+  before any implementation code is written. Use after creating a worktree,
+  picking a branch, or any time the user wants to "set the workspace",
+  "wire the assignment to a branch", or per the Workspace Before Code
+  playbook. Validates frontmatter via `syntaur doctor --assignment --json`
+  before writing — refuses to touch a malformed file.
+license: MIT
+metadata:
+  author: prong-horn
+  version: "1.0.0"
+---
+
+# Set Workspace
+
+Write the four canonical `workspace.*` fields in `assignment.md` frontmatter
+so that the PreToolUse write-boundary hook will allow implementation work.
+Validates the file first via `syntaur doctor --assignment --json` and
+refuses to write on errors.
+
+This skill implements the **Workspace Before Code** playbook: never write
+implementation code until workspace fields are set.
+
+## When NOT to use this skill
+
+- The workspace fields are already set correctly. Read the assignment.md
+  first; if all four fields match the intended values, do nothing.
+- You want to create the worktree itself — use `/syntaur-worktree`, which
+  composes worktree creation AND workspace field updates in one move.
+- The assignment is in a terminal status (`completed`, `failed`,
+  `cancelled`). Reopen it first if you really need to change workspace.
+
+## Step 1: Resolve the assignment file
+
+Read `.syntaur/context.json` from the current working directory. Extract
+`assignmentDir`. The target file is `<assignmentDir>/assignment.md`.
+
+If no context, abort with: "No active assignment. Run `grab-assignment`
+first."
+
+## Step 2: Pre-write validation
+
+```bash
+syntaur doctor --assignment <assignmentDir>/assignment.md --json
+```
+
+Parse the JSON output. If `ok: false`, refuse to proceed. Report the
+`errors[]` to the user verbatim and recommend they fix the underlying
+frontmatter (or run `syntaur doctor` for the broader project context).
+**Do not write any changes if the file is malformed.**
+
+## Step 3: Gather inputs
+
+Required (one or more — at minimum the user must specify enough to fill
+all four fields):
+
+- `--repository <path>` — repo root (typically `git rev-parse --show-toplevel`).
+- `--worktree-path <path>` — usually `<repository>/.worktrees/<branch>`
+  per the repo-local convention.
+- `--branch <name>` — current branch (`git rev-parse --abbrev-ref HEAD`).
+- `--parent-branch <name>` — typically `main`.
+
+Defaults the skill should auto-detect when not supplied:
+
+- `repository` ← `git -C $(pwd) rev-parse --show-toplevel`.
+- `branch` ← `git -C $(pwd) rev-parse --abbrev-ref HEAD`.
+- `worktreePath` ← `$(pwd)` (when invoked from the worktree itself).
+- `parentBranch` ← prompt the user; do not invent.
+
+## Step 4: Read assignment.md
+
+Locate the `workspace:` block in the frontmatter. It must look like:
+
+```yaml
+workspace:
+  repository: <value-or-null>
+  worktreePath: <value-or-null>
+  branch: <value-or-null>
+  parentBranch: <value-or-null>
+```
+
+If the block is missing entirely, refuse to write — `doctor --assignment`
+should have caught it; this is a defensive check.
+
+## Step 5: Write the four fields
+
+Replace the four lines in place. Quote string values containing special
+characters; use `null` literal for unset fields. Preserve the rest of the
+frontmatter and body bit-for-bit.
+
+Bump the top-level `updated` timestamp in the frontmatter.
+
+## Step 6: Re-validate
+
+Re-run `syntaur doctor --assignment <path> --json`. Expect `ok: true`. If
+the post-write validation fails, restore the prior file content and report
+the error — do not leave the file in a half-written state.
+
+## Step 7: Report to User
+
+Summarize:
+
+- Path of the modified assignment.md.
+- The four field values that were written.
+- Confirmation that post-write `doctor --assignment` passed.
+- Reminder: implementation work is now unblocked by the write-boundary hook.

package/platforms/codex/skills/syntaur-protocol/SKILL.md

@@ -111,6 +111,10 @@ ls ~/.syntaur/playbooks/*.md 2>/dev/null
 - Write handoffs with enough context for another agent or human to continue cleanly. Record decisions in `decision-record.md` with Status / Context / Decision / Consequences — downstream dependents auto-load these during grab.
 - Commit frequently with messages referencing the assignment slug.
 
+### Proof artifacts (opt-in)
+
+Agents can attach typed evidence so a human reviewer can verify work in seconds without re-running it. Use `syntaur capture` after a meaningful change is verified, then `syntaur proof build` to render `proof.html` at the assignment dir. Artifact kinds at v1: `screenshot`, `video`, `asciinema`, `http`, `text`. Criterion linkage is optional (0-based index into `## Acceptance Criteria`); untagged or stale-out-of-range artifacts render in a final "Other artifacts" section. Files live under `<assignmentDir>/proof/<criterion|untagged>/<id>.<ext>`. The `complete-assignment` skill mentions the proof page in its final report. **No completion gate** — proof is purely opt-in for v1.
+
 ## References
 
 For the full directory structure, lifecycle state table, and detailed file ownership rules, read:

package/platforms/codex/skills/syntaur-protocol/references/protocol-summary.md

@@ -80,3 +80,11 @@ Protocol version: **2.0**
 10. **Comments** are appended to `comments.md` via `syntaur comment <slug> "body" [--type question|note|feedback] [--reply-to <id>]`. Never edit `comments.md` directly. Questions carry a `resolved` flag toggled in the dashboard.
 11. **Cross-assignment work** is requested via `syntaur request <target> "text"` — appends to the target's `## Todos` annotated `(from: <source>)`.
 12. **Agent sessions** in `syntaur.db` must use real agent-runtime session IDs. Synthesized UUIDs are rejected. Plugins for Claude Code / Codex populate `.syntaur/context.json` with the real id via a SessionStart hook; other agents should source it from their runtime and pass `--session-id` explicitly.
+
+## Proof artifacts (opt-in)
+
+Agents can attach typed evidence to an assignment so a human reviewer can verify the work in seconds without re-running it.
+
+- `syntaur capture --kind <screenshot|video|asciinema|http|text> [--file <path>] [--criterion <index>] [--note <text>] [target]` — record an artifact for the active assignment. Criterion linkage is optional (0-based index into the `## Acceptance Criteria` checklist). For `--kind=text`, supply `--note` and omit `--file`. For `--kind=http`, supply `--file` (transcript) or `--note` (inline summary).
+- `syntaur proof build [target]` — render `proof.html` and `proof.md` at the assignment dir, walking the `## Acceptance Criteria` list and embedding tagged artifacts inline beneath each criterion. Untagged or stale (out-of-range) captures land in a final "Other artifacts" section. Atomic overwrite — safe to re-run.
+- Artifacts are stored under `<assignmentDir>/proof/<criterion|untagged>/<id>.<ext>`. The DB row lives in `~/.syntaur/syntaur.db` alongside session tracking. No completion gate — proof is purely opt-in for v1.

package/platforms/codex/skills/syntaur-worktree/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: syntaur-worktree
+description: >-
+  Create a git worktree for a Syntaur assignment under
+  `<repo>/.worktrees/<branch>`, claim the assignment, and bind the new
+  workspace to the agent session — all in one move. Use when the user wants
+  to "make a worktree", "branch + worktree for this assignment", "spin up an
+  isolated workspace", or set up parallel work on a different assignment.
+license: MIT
+metadata:
+  author: prong-horn
+  version: "1.0.0"
+---
+
+# Syntaur Worktree
+
+Atomic worktree-and-grab for a Syntaur assignment. Composes four lower-level
+operations:
+
+1. `git worktree add` (via `syntaur worktree create`) — repo-local convention
+   `<repository>/.worktrees/<branch>`.
+2. Update `assignment.md` workspace fields (done by the same CLI verb,
+   transactionally — rolls back the worktree on write failure).
+3. `syntaur assign` + `syntaur start` — claim the assignment for this agent
+   and transition to `in_progress`.
+4. Write `.syntaur/context.json` inside the new worktree so the session is
+   bound there.
+
+## When NOT to use this skill
+
+- You only want to create a git worktree outside of Syntaur — use
+  `git worktree add` directly. This skill assumes a Syntaur assignment exists.
+- The assignment already has a worktree path set in `assignment.md` workspace
+  fields. Check first; reuse the existing path.
+- You want to grab an assignment without creating a worktree — use
+  `/grab-assignment` directly.
+
+## Step 1: Resolve inputs
+
+Required arguments from the user (or interactive prompts):
+
+- `--project <slug>` (omit for standalone assignments — pass `--id <uuid>`)
+- `--assignment <slug-or-uuid>`
+- `--branch <name>` — the new branch name (also the worktree dir name)
+- `--repository <path>` — defaults to current working directory; usually the
+  repo root the assignment lives in
+- `--parent-branch <name>` — defaults to `main`
+
+The computed worktree path is **always**
+`<repository>/.worktrees/<branch>`. Never `.claude/worktrees/`. Never
+`~/.syntaur/worktrees/...`. The repo-local convention is enforced.
+
+## Step 2: Pre-flight
+
+- Confirm `<repository>/.git` exists.
+- Confirm the branch does NOT already exist (otherwise the CLI will fail
+  cleanly — surface that error).
+- Confirm the assignment is not in a terminal status. If it is, suggest
+  `syntaur reopen` first.
+
+## Step 3: Create worktree + record workspace
+
+```bash
+syntaur worktree create \
+  --repository <repository> \
+  --branch <branch> \
+  --parent-branch <parent-branch> \
+  --assignment <slug-or-uuid> \
+  --project <project-slug>
+```
+
+The CLI handles atomicity — on any failure the worktree (if created) and the
+new branch are removed.
+
+## Step 4: Claim the assignment
+
+```bash
+syntaur assign <assignment> --agent <your-agent-name> --project <project-slug>
+syntaur start <assignment> --project <project-slug>   # only if status was pending
+```
+
+Skip `start` for any non-`pending` status — never rewind a `review`,
+`completed`, or `failed` assignment.
+
+## Step 5: Bind the new worktree to your session
+
+`cd` into the new worktree path. Write
+`<worktreePath>/.syntaur/context.json` mirroring the format produced by
+`/grab-assignment` (projectSlug, assignmentSlug, projectDir, assignmentDir,
+workspaceRoot, title, branch, sessionId, transcriptPath, grabbedAt).
+
+If the runtime exposes a real session id (e.g. Claude Code's
+`~/.claude/sessions/`), include it. Otherwise omit `sessionId` entirely; the
+SessionStart hook will populate it on next run.
+
+## Step 6: Register the session with the dashboard
+
+```bash
+syntaur track-session \
+  --project <project-slug> --assignment <assignment-slug> \
+  --agent <your-agent-name> \
+  --session-id <real-id> \
+  --path "$(pwd)"
+```
+
+Skip if no real session id is available. Surface the failure non-fatally.
+
+## Step 7: Report to User
+
+Summarize:
+
+- New worktree path (`<repository>/.worktrees/<branch>`).
+- Branch + parent branch.
+- Assignment slug, project slug, new status.
+- Whether the session was registered with the dashboard.
+- Reminder to `cd` into the new worktree if the parent shell is not already
+  there.

package/skills/add-memory/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: add-memory
+description: >-
+  Capture a project-level Syntaur memory (durable context like a convention,
+  decision rationale, or constraint) under a project's `memories/` directory.
+  Use when the user wants to "save this to memory", "remember for the project",
+  "capture this decision", "add a project memory", or pin reusable context that
+  should outlive any single assignment. Writes via the CLI so the
+  CLI-managed `_index.md` is never touched directly.
+license: MIT
+metadata:
+  author: prong-horn
+  version: "1.0.0"
+---
+
+# Add Memory
+
+Add a memory entry to a Syntaur project. Writes
+`<projectDir>/memories/<slug>.md` and regenerates `_index.md` server-side via
+`syntaur memory add` — the agent never edits `_index.md` directly per the
+file-ownership protocol.
+
+## When NOT to use this skill
+
+- The information is a **pointer to an external system** (URL, dashboard,
+  ticket) — use `add-resource` instead.
+- The information is the user-global Claude Code memory at
+  `~/.claude/projects/<...>/memory/MEMORY.md` — that's a different system
+  managed by the auto-memory feature, NOT Syntaur project memories.
+- The information is single-assignment scratch — put it in the assignment's
+  `scratchpad.md`.
+
+## Step 1: Resolve project
+
+If `.syntaur/context.json` is present and has `projectSlug`, default to that.
+Otherwise ask the user which project to add the memory to.
+
+## Step 2: Gather inputs
+
+Required:
+
+- `--name <human readable>` — display name for the memory.
+- `--source <text>` — where this memory came from (e.g. "conversation
+  2026-05-08", a decision-record reference, a doc URL).
+
+Optional:
+
+- `--scope <scope>` — defaults to `project`. Common values: `project`,
+  `architecture`, `policy`.
+- `--source-assignment <slug>` — assignment slug this memory was captured
+  during (helps trace the origin).
+- `--related-assignments <slug,slug,...>` — comma-separated assignment slugs
+  this memory is relevant to.
+- `--slug <slug>` — override the auto-generated kebab-case slug.
+
+## Step 3: Run `syntaur memory add`
+
+```bash
+syntaur memory add \
+  --project <project-slug> \
+  --name "<name>" \
+  --source "<text>" \
+  [--scope <scope>] \
+  [--source-assignment <slug>] \
+  [--related-assignments <slug,slug>] \
+  [--slug <slug>] \
+  [--force]
+```
+
+The CLI:
+
+1. Validates the project exists.
+2. Writes `<projectDir>/memories/<slug>.md` with the canonical frontmatter
+   (`name`, `source`, `scope`, `sourceAssignment`, `relatedAssignments`,
+   `created`, `updated`).
+3. Regenerates `<projectDir>/memories/_index.md` from the directory contents.
+4. Refuses to overwrite an existing memory without `--force`.
+
+**Do not write to `_index.md` directly under any circumstances** — that file
+is owned by the CLI per the file-ownership protocol.
+
+## Step 4: Open the new memory file (optional)
+
+If the user wants to flesh out the body content beyond the placeholder, open
+`<projectDir>/memories/<slug>.md` and edit the body. The frontmatter is
+already correct; only edit content below the second `---`.
+
+## Step 5: Report to User
+
+Summarize:
+
+- Memory slug and absolute path.
+- Project that received the memory.
+- Index regenerated (with the new total).
+- Suggested next step: edit the body to capture load-bearing context, or
+  open the dashboard to see the new entry.