syntaur 0.8.0 → 0.12.0

package/platforms/codex/commands/add-memory.md

@@ -0,0 +1,16 @@
+---
+description: Capture a project-level Syntaur memory under <projectDir>/memories/ via the CLI
+---
+
+# /add-memory
+
+Add a project-scoped memory entry. Writes `<projectDir>/memories/<slug>.md` and regenerates `_index.md` server-side via `syntaur memory add` — the agent never touches `_index.md` directly per the file-ownership protocol.
+
+Follow the `add-memory` skill in full. Summary:
+
+1. Resolve project from `.syntaur/context.json` or ask.
+2. Gather `--name --source [--scope --source-assignment --related-assignments --slug]`.
+3. Run `syntaur memory add ...`.
+4. Optionally edit the body of the new file to flesh out content.
+
+Distinct from the user-global Claude Code auto-memory at `~/.claude/projects/<...>/memory/`.

package/platforms/codex/commands/add-resource.md

@@ -0,0 +1,14 @@
+---
+description: Register a project-level resource (link to dashboard, doc, ticket) under a Syntaur project
+---
+
+# /add-resource
+
+Add a resource entry under `<projectDir>/resources/<slug>.md` and regenerate `_index.md` via the CLI. The agent never edits `_index.md` directly.
+
+Follow the `add-resource` skill in full. Summary:
+
+1. Resolve project from `.syntaur/context.json` or ask.
+2. Gather `--name --source [--category --related-assignments --slug]`.
+3. Run `syntaur resource add ...`.
+4. Verify the slug file and refreshed index.

package/platforms/codex/commands/list-assignments.md

@@ -0,0 +1,13 @@
+---
+description: List Syntaur assignments across projects with filters (status, project, tag, age)
+---
+
+# /list-assignments
+
+Cross-project assignment listing via `syntaur ls`. Supports `--status`, `--project`, `--tag`, `--age`, `--json`. Different from the interactive `syntaur browse` TUI — emits scriptable output.
+
+Follow the `list-assignments` skill in full. Summary:
+
+1. Map user prose to `syntaur ls` flags (e.g. "pending" → `--status pending`, "this week" → `--age 7d`, "tagged X and Y" → `--tag X,Y`).
+2. Run the CLI.
+3. Present the table or pass the `--json` payload downstream.

package/platforms/codex/commands/log-progress.md

@@ -0,0 +1,14 @@
+---
+description: Append a timestamped entry to the active assignment's progress.md and bump frontmatter
+---
+
+# /log-progress
+
+Append a structured timestamped entry to `<assignmentDir>/progress.md` and bump its `entryCount` and `updated` frontmatter fields. Implements the Keep Records Updated playbook.
+
+Follow the `log-progress` skill in full. Summary:
+
+1. Read `.syntaur/context.json`. Abort if no active assignment.
+2. Compose a concise entry with action verbs, file paths, commit refs, and verification commands.
+3. Read the existing `progress.md`, increment `entryCount`, set `updated = now`, append the new entry under the existing body.
+4. Re-read to confirm schema-valid frontmatter; restore on schema failure.

package/platforms/codex/commands/replan.md

@@ -0,0 +1,15 @@
+---
+description: Bump the active assignment to a new plan version (plan-vN.md) per the Plan Versioning playbook
+---
+
+# /replan
+
+Create a new versioned plan (`plan-v<N>.md`) for the active Syntaur assignment after the prior plan has been implemented or scope has shifted significantly.
+
+Follow the `replan` skill in full. Summary:
+
+1. Read `.syntaur/context.json`. Abort if no active assignment.
+2. If the prior plan still has unchecked tasks, confirm with the user before proceeding.
+3. Run `syntaur plan version --assignment <slug> [--project <slug>]`. The CLI handles file naming, supersede-rewrite of `assignment.md` `## Todos`, and carrying forward unchecked todos.
+4. Fill in the new plan body (Objective, Tasks, Verification).
+5. Append a progress.md entry.

package/platforms/codex/commands/resume-session.md

@@ -0,0 +1,15 @@
+---
+description: Re-orient a fresh session on the active Syntaur assignment without re-reading the full transcript
+---
+
+# /resume-session
+
+Print a compact orientation block from the latest saved session summary, `.syntaur/context.json`, and any open handoff. Idempotent — does not mutate state.
+
+Follow the `resume-session` skill in full. Summary:
+
+1. Run `syntaur session resume`. Surface its output.
+2. Read the latest `<assignmentDir>/sessions/<sid>/summary.md` if reported.
+3. Read `<assignmentDir>/handoff.md` if present and non-placeholder (canonical single-file handoff).
+4. Read `assignment.md` and the tail of `progress.md`.
+5. Report active project / assignment / branch / next concrete action.

package/platforms/codex/commands/set-workspace.md

@@ -0,0 +1,15 @@
+---
+description: Populate the four workspace.* fields in the active assignment.md per the Workspace Before Code playbook
+---
+
+# /set-workspace
+
+Write `repository`, `worktreePath`, `branch`, `parentBranch` into the assignment.md frontmatter. Validates the file via `syntaur doctor --assignment <path> --json` before writing — refuses to touch a malformed file.
+
+Follow the `set-workspace` skill in full. Summary:
+
+1. Read `.syntaur/context.json` to find `assignmentDir`.
+2. Run `syntaur doctor --assignment <path> --json`. Refuse on `ok: false`.
+3. Auto-detect defaults from `git rev-parse` when not supplied; ask user for missing fields.
+4. Replace the four `workspace:` block lines and bump the top-level `updated` timestamp.
+5. Re-validate via `doctor --assignment`. Restore on post-write failure.

package/platforms/codex/commands/syntaur-worktree.md

@@ -0,0 +1,15 @@
+---
+description: Create a repo-local worktree for the active Syntaur assignment and bind the session to it
+---
+
+# /syntaur-worktree
+
+Atomic worktree-and-grab. Composes `syntaur worktree create` + `syntaur assign` + `syntaur start` + writing `.syntaur/context.json` in the new workspace. Worktree path is always `<repository>/.worktrees/<branch>`.
+
+Follow the `syntaur-worktree` skill in full. Summary:
+
+1. Resolve `--project --assignment --branch [--repository --parent-branch]`.
+2. Run `syntaur worktree create ...` (atomic: rolls back on assignment.md write failure).
+3. Run `syntaur assign <assignment> --agent <name>` then `syntaur start <assignment>` (only when status was pending).
+4. `cd` into the new worktree path, write `.syntaur/context.json`.
+5. Run `syntaur track-session` to register with the dashboard.

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

@@ -88,3 +88,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.
 11. Cross-assignment work is requested via `syntaur request <source> <target> "text"` — appends to the target's `## Todos` annotated `(from: <source>)`.
 12. Session continuity (mid-assignment) lives at `sessions/<session-id>/summary.md` inside the assignment dir — one document per session id, overwritten on every save (via `/save-session-summary`). On resume, pick the latest by `summary.md` file mtime. Older summaries accumulate as immutable history; never delete them. Distinct from `handoff.md`, which is the assignment-level cross-ticket outbound at completion. `syntaur doctor` intentionally ignores `sessions/`. **Codex has no `PreCompact` hook event** — invoke `/save-session-summary` manually before compaction or session end.
+
+## 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`.
+- `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/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.

package/platforms/codex/skills/add-resource/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: add-resource
+description: >-
+  Register a project-level resource (link to a dashboard, doc, ticket, or
+  external system) under a Syntaur project. Use when the user wants to "add a
+  resource", "save this link to the project", "track this dashboard", "add a
+  reference doc", or otherwise capture a pointer to an external system the
+  project depends on.
+license: MIT
+metadata:
+  author: prong-horn
+  version: "1.0.0"
+---
+
+# Add Resource
+
+Add a resource entry to a Syntaur project. Writes
+`<projectDir>/resources/<slug>.md` and regenerates `<projectDir>/resources/_index.md`
+via the CLI — the agent never edits `_index.md` directly (it is a
+CLI-managed file per the file-ownership protocol).
+
+## When NOT to use this skill
+
+- The information is **session-scoped knowledge**, not a pointer to an
+  external system — use `add-memory` instead.
+- The link is specific to a single assignment (assignment-level scratch) —
+  put it in that assignment's `scratchpad.md`.
+- The resource already exists. Read `<projectDir>/resources/_index.md` first
+  to check; pass `--force` only if you intend to overwrite.
+
+## 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 resource to.
+
+## Step 2: Gather inputs
+
+Required:
+
+- `--name <human readable>` — display name for the resource.
+- `--source <url-or-path>` — the link or path to the resource itself.
+
+Optional:
+
+- `--category <name>` — short category tag (e.g. `dashboard`, `doc`,
+  `ticket`, `runbook`, `repo`).
+- `--related-assignments <slug,slug,...>` — comma-separated assignment slugs
+  this resource is relevant to.
+- `--slug <slug>` — override the auto-generated kebab-case slug.
+
+## Step 3: Run `syntaur resource add`
+
+```bash
+syntaur resource add \
+  --project <project-slug> \
+  --name "<name>" \
+  --source <url-or-path> \
+  [--category <name>] \
+  [--related-assignments <slug,slug>] \
+  [--slug <slug>] \
+  [--force]
+```
+
+The CLI:
+
+1. Validates the project exists.
+2. Writes `<projectDir>/resources/<slug>.md` with the canonical frontmatter
+   (`name`, `category`, `source`, `relatedAssignments`, `created`,
+   `updated`).
+3. Regenerates `<projectDir>/resources/_index.md` from the directory contents.
+4. Refuses to overwrite an existing resource without `--force`.
+
+## Step 4: Verify
+
+The CLI prints the slug file path and the new index size. Read both back if
+the user asked for confirmation.
+
+## Step 5: Report to User
+
+Summarize:
+
+- Resource slug and absolute path.
+- Project that received the resource.
+- Index regenerated (with the new total).
+- Suggested next step: open the dashboard or `_index.md` to see the new entry.

package/platforms/codex/skills/capture-artifacts/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: capture-artifacts
+description: >-
+  Capture typed proof artifacts (screenshot, video, asciinema, http transcript,
+  text note) for the active Syntaur assignment so a human reviewer can verify
+  the work in seconds without re-running it. Use after a meaningful change is
+  verified, especially when an acceptance criterion is now demonstrably met.
+license: MIT
+metadata:
+  author: prong-horn
+  version: "0.1.0"
+---
+
+# Capture Artifacts
+
+Attach proof to your work. Reviewers should be able to scroll a single page (`proof.html`) and judge "yep that's what I wanted" or "nope that's not right" — without re-executing anything.
+
+## Input
+
+No arguments. Reads `.syntaur/context.json` from the current working directory to identify the active assignment.
+
+## Step 1: Decide whether to capture
+
+Capture an artifact when **any** of these is true:
+- An acceptance criterion is now demonstrably met (most common trigger).
+- A user-facing behavior changed in a way a screenshot, video, transcript, or short text note can show.
+- A bug fix produces a before/after worth showing (capture the after; the diff is the before).
+
+Skip when:
+- The change is purely internal (refactor, type tightening) with no observable effect.
+- The change is already covered by a passing automated test that the reviewer can run trivially.
+
+Linkage to a specific criterion is **optional**. Untagged artifacts are fine — they land in a "Other artifacts" section on the proof page.
+
+## Step 2: Pick the kind by work type
+
+| Work type | Preferred kind | Notes |
+|-----------|---------------|-------|
+| Web UI change | `screenshot` (single state) or `video` (interaction) | Use the smallest medium that conveys the proof. Screenshots beat videos when one frame suffices. |
+| CLI command output | `asciinema` (preferred) or `text` | Asciinema records the actual session; text is fine when output is short and static. |
+| Backend API change | `http` (request/response transcript) | Capture the curl invocation + response body. |
+| Migration / schema / config | `text` with a `--note` describing the before/after | Or `http` for an API verification call. |
+| Anything ambiguous | `text` with `--note` | Always available. Written notes are better than skipped captures. |
+
+## Step 3: Run `syntaur capture`
+
+```bash
+# File-based (screenshot, video, asciinema, http transcript)
+syntaur capture --kind <type> --file <path> [--criterion <index>] [--note <text>] \
+  [--project <slug> <assignment-slug>]
+
+# Text-only (no --file)
+syntaur capture --kind text --note "<what you verified>" [--criterion <index>] \
+  [--project <slug> <assignment-slug>]
+```
+
+Rules:
+- `--kind=text` requires `--note` and forbids `--file`.
+- `--kind=http` accepts either `--file` (a transcript) or `--note` (an inline summary). At least one is required.
+- All other kinds (`screenshot`, `video`, `asciinema`) require `--file`. The CLI rejects nonexistent / non-file paths.
+- `--criterion <index>` is optional — pass the **0-based** index into the `## Acceptance Criteria` checklist when you want to anchor the artifact to a specific criterion.
+- If you have a `.syntaur/context.json` in the cwd, the positional target argument is unnecessary; otherwise pass `--project <slug> <assignment-slug>` or a bare assignment UUID.
+
+The CLI copies the file (if any) under `<assignmentDir>/proof/<criterion|untagged>/<id>.<ext>` and inserts a row in `~/.syntaur/syntaur.db`. Output prints the artifact id and absolute path.
+
+## Step 4: Optional — refresh the proof page
+
+```bash
+syntaur proof build [--project <slug> <assignment-slug>]
+```
+
+This walks `## Acceptance Criteria` and renders `proof.html` + `proof.md` at the assignment dir, embedding tagged artifacts inline beneath their criteria and untagged/stale ones in a final "Other artifacts" section. Atomic overwrite — safe to re-run after every capture, or once at completion. The rendered page works in any browser; no desktop-app dependency.
+
+The `complete-assignment` skill mentions the proof page path in its final report so the reviewer can open it.
+
+## Step 5: Record the capture (per `keep-records-updated` playbook)
+
+The `keep-records-updated` playbook recommends running `syntaur capture` whenever the change is visually or behaviorally observable. Append a brief mention to `progress.md` if it adds context (e.g. "captured login-flow video against criterion 2"). Skipping a capture is fine — proof is opt-in for v1; there is no completion gate.
+
+## Notes
+
+- Artifacts are local-only in v1. Cloud upload is not available.
+- Stale `criterion_index` (e.g. when a criterion is later deleted or reordered) renders under "Other artifacts" with a "(was tagged criterion N — no longer present)" annotation. The artifact is not lost.
+- Storage stays out of git by default — `~/.syntaur/` is outside any tracked tree.

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

@@ -6,7 +6,7 @@ description: >-
 license: MIT
 metadata:
   author: prong-horn
-  version: "1.1.0"
+  version: "1.2.0"
 ---
 
 # Complete Assignment
@@ -143,4 +143,5 @@ Summarize:
 - Assignment slug and title
 - New status (review or completed)
 - Number of acceptance criteria met vs total
+- If `<assignmentDir>/proof.html` exists, include its absolute path so the reviewer can open it directly in a browser. Mention briefly which criteria have artifacts attached. (Proof is opt-in — its absence is not a blocker.)
 - If transitioned to `review`, a human reviewer will check the work. If any criteria were unmet, they may send it back to `in_progress`.

package/platforms/codex/skills/list-assignments/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: list-assignments
+description: >-
+  List Syntaur assignments across all projects with filters by status,
+  project, tag, and age. Use when the user wants to "see all assignments",
+  "list pending work", "show in_progress assignments", "what's open",
+  "find assignments tagged X", or otherwise query the cross-project board
+  non-interactively. Different from the interactive `browse` TUI — emits
+  scriptable output (table or JSON).
+license: MIT
+metadata:
+  author: prong-horn
+  version: "1.0.0"
+---
+
+# List Assignments
+
+Cross-project assignment listing using `syntaur ls`. Supports filters by
+status, project, tag, and age. Emits a compact aligned table by default;
+`--json` produces machine-readable output suitable for piping into other
+tools.
+
+## When NOT to use this skill
+
+- The user wants to interactively browse and act on assignments — use
+  `syntaur browse` (the Ink TUI) instead.
+- The user wants details for a single assignment they already know — open
+  its `assignment.md` directly.
+- The user wants project-level rollups (totals, blocked counts) — that's the
+  dashboard, not `ls`.
+
+## Step 1: Map user prose to filters
+
+Common requests → flags:
+
+- "pending assignments" → `--status pending`
+- "in-progress" / "active" → `--status in_progress`
+- "stuff blocked" → `--status blocked`
+- "everything in <project>" → `--project <slug>`
+- "tagged with X" / "labeled X" → `--tag X`
+- "must have all of X and Y" → `--tag X,Y` (AND semantics)
+- "from this week" → `--age 7d`
+- "last 24 hours" → `--age 24h`
+- "this month" → `--age 30d` (or `1m`)
+- "as JSON" / "for piping" → `--json`
+
+Multiple filters compose (intersected).
+
+## Step 2: Run `syntaur ls`
+
+```bash
+syntaur ls [--status <list>] [--project <slug>] [--tag <list>] [--age <duration>] [--json]
+```
+
+Supported `--age` units: `h` (hours), `d` (days), `w` (weeks), `m` (~30 days).
+
+## Step 3: Present results
+
+Default output is a table with columns: PROJECT, SLUG, STATUS, PRIORITY,
+ASSIGNEE, UPDATED, TITLE. If the user asked for a count or a follow-up
+action ("which one is highest priority?"), parse the table or re-run with
+`--json` and pick programmatically.
+
+## Step 4: Report to User
+
+If interactive:
+
+- Summarize the count and any obvious patterns (e.g. "5 pending in
+  syntaur-meta, 3 blocked across other projects").
+- Suggest a next action when applicable (e.g. "want to grab the top-priority
+  pending one?").
+
+If scripted (`--json`), pass the parsed JSON downstream without re-rendering.

package/platforms/codex/skills/log-progress/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: log-progress
+description: >-
+  Append a timestamped entry to the active assignment's `progress.md`,
+  bumping `entryCount` and `updated` in its frontmatter. Use after every
+  meaningful action — completing an acceptance criterion, finishing a plan
+  task, hitting a blocker, deciding on an approach — per the Keep Records
+  Updated playbook. Triggers on "log progress", "note progress", "record
+  this in progress", or whenever the playbook says to update records.
+license: MIT
+metadata:
+  author: prong-horn
+  version: "1.0.0"
+---
+
+# Log Progress
+
+Append a structured timestamped entry to the active assignment's
+`<assignmentDir>/progress.md`, and update its frontmatter. Markdown-only —
+no CLI verb. Idempotent in the sense that re-running with the same body
+produces a duplicate entry, which is intentional (timestamps differ).
+
+This skill implements the **Keep Records Updated** playbook: agents must keep
+records current in real-time, especially after every meaningful action.
+
+## When NOT to use this skill
+
+- The action belongs in `decision-record.md` (architecturally significant
+  decisions with rationale) — write to that file, not progress.md.
+- The information is for the next session of the SAME assignment — that's
+  `/save-session-summary`.
+- The information is a question for the user — write to `comments.md` via
+  `syntaur comment` (CLI-mediated).
+- The information is a follow-up assignment idea — open a new assignment
+  via `/create-assignment`.
+
+## Step 1: Verify there is an active assignment
+
+Read `.syntaur/context.json` from the current working directory. Extract
+`assignmentDir`. If missing, abort with: "No active assignment. Run
+`grab-assignment` first."
+
+## Step 2: Compose the entry
+
+The entry should be concise, factual, and link-rich. Suggested structure:
+
+```markdown
+## <ISO 8601 UTC timestamp> — <one-line summary>
+
+- What changed (action verbs).
+- Files touched: `path/to/file.ts:line`, `another.ts`.
+- Commits: `<short-sha>` (one per logical change).
+- Verification: `npm test src/...`, `node dist/index.js x --help`, etc.
+
+Optional notes paragraph.
+```
+
+Use ISO 8601 with `Z` suffix (e.g. `2026-05-08T20:13:00Z`). Use absolute
+file paths or repo-relative paths consistently.
+
+## Step 3: Read existing progress.md
+
+Read `<assignmentDir>/progress.md`. Extract:
+
+- Current `entryCount` from the frontmatter.
+- The full body (everything after the second `---`).
+
+If `progress.md` doesn't exist, abort and tell the user to re-grab the
+assignment (the file should always exist for an in-progress assignment).
+
+## Step 4: Compute new frontmatter
+
+- `entryCount`: increment by 1.
+- `updated`: set to current ISO timestamp.
+- Other fields (`assignment`, `generated`): preserve as-is.
+
+## Step 5: Write the file
+
+Write back the file with the updated frontmatter and the new entry **prepended**
+to the body (newest first), per the Keep Records Updated playbook and
+`skills/syntaur-protocol/references/protocol-summary.md`. Reverse-chronological
+order: the new `## <ISO 8601 timestamp>` heading sits immediately after the
+`# Progress` H1, with one blank line separating it from any prior entry.
+
+Layout:
+
+```markdown
+# Progress
+
+## <new ISO timestamp>
+
+<new entry body>
+
+## <prior ISO timestamp>
+
+<prior entry body>
+
+## <even-older ISO timestamp>
+
+<even-older entry body>
+```
+
+If the existing body is the placeholder text "No progress yet.", replace it
+with the new entry instead of preserving the placeholder.
+
+> **Why prepend:** the dashboard and downstream readers expect the most recent
+> entry first. Appending at the end would silently break the convention
+> documented in `~/.syntaur/playbooks/keep-records-updated.md`.
+
+## Step 6: Verify schema
+
+Confirm by re-reading the file:
+
+- Starts with `---`, then frontmatter, then `---`.
+- `entryCount` is a non-negative integer.
+- `updated` matches the timestamp you wrote.
+- The new entry's `## <timestamp>` heading is present.
+
+If the file fails schema check, restore the prior content and report the
+error — do not leave it partially written.
+
+## Step 7: Report to User
+
+Summarize:
+
+- Path of the modified `progress.md`.
+- New `entryCount`.
+- One-line summary of the entry that was logged.