syntaur 0.2.0 → 0.3.3

package/platforms/claude-code/hooks/session-cleanup.sh

@@ -34,39 +34,29 @@ SESSION_ID=$(jq -r '.sessionId // empty' "$CONTEXT_FILE" 2>/dev/null)
 MISSION_SLUG=$(jq -r '.projectSlug // empty' "$CONTEXT_FILE" 2>/dev/null)
 ASSIGNMENT_SLUG=$(jq -r '.assignmentSlug // empty' "$CONTEXT_FILE" 2>/dev/null)
 
-PORT=$(cat "$HOME/.syntaur/dashboard-port" 2>/dev/null || echo "4800")
-
-# --- Step 5: If no session was registered, try to auto-register (requires project+assignment) ---
+# Fall back to the SessionEnd stdin payload if context.json didn't have the id.
+# Claude Code passes session_id on stdin for SessionEnd.
 if [ -z "$SESSION_ID" ]; then
-  # Can only auto-register if we have project and assignment context
-  if [ -z "$MISSION_SLUG" ] || [ -z "$ASSIGNMENT_SLUG" ]; then
-    exit 0
-  fi
-
-  # Generate a session ID for the log entry
-  SESSION_ID=$(uuidgen 2>/dev/null || cat /proc/sys/kernel/random/uuid 2>/dev/null || echo "ses-$(date +%s)")
-  # Lowercase the UUID (uuidgen on macOS outputs uppercase)
-  SESSION_ID=$(echo "$SESSION_ID" | tr '[:upper:]' '[:lower:]')
+  SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // empty' 2>/dev/null)
+fi
 
-  RESPONSE=$(curl -sf -X POST "http://localhost:${PORT}/api/agent-sessions" \
-    -H "Content-Type: application/json" \
-    -d "{\"projectSlug\": \"${MISSION_SLUG}\", \"assignmentSlug\": \"${ASSIGNMENT_SLUG}\", \"agent\": \"claude\", \"sessionId\": \"${SESSION_ID}\", \"path\": \"${CWD}\"}" \
-    2>/dev/null) || true
+# No real session id available — exit quietly. We never synthesize one.
+[ -z "$SESSION_ID" ] && exit 0
 
-  # If registration succeeded, update the context file with the session ID
-  if [ -n "$RESPONSE" ]; then
-    jq --arg sid "$SESSION_ID" '. + {sessionId: $sid}' "$CONTEXT_FILE" > "${CONTEXT_FILE}.tmp" 2>/dev/null \
-      && mv "${CONTEXT_FILE}.tmp" "$CONTEXT_FILE" 2>/dev/null || true
-  fi
+# --- Dashboard endpoint resolution (mirror session-start.sh exactly so start
+# and end hooks always target the same host:port) ---
+PORT="${SYNTAUR_DASHBOARD_PORT:-}"
+if [ -z "$PORT" ]; then
+  PORT=$(cat "$HOME/.syntaur/dashboard-port" 2>/dev/null || echo "4800")
 fi
 
-# --- Step 6: Mark session as stopped via dashboard API ---
+# --- Step 5: Mark session as stopped via dashboard API ---
 BODY="{\"status\": \"stopped\"}"
 if [ -n "$MISSION_SLUG" ]; then
   BODY="{\"status\": \"stopped\", \"projectSlug\": \"${MISSION_SLUG}\"}"
 fi
 
-curl -sf -X PATCH "http://localhost:${PORT}/api/agent-sessions/${SESSION_ID}/status" \
+curl -sf --max-time 3 -X PATCH "http://127.0.0.1:${PORT}/api/agent-sessions/${SESSION_ID}/status" \
   -H "Content-Type: application/json" \
   -d "$BODY" \
   -o /dev/null 2>/dev/null || true

package/platforms/claude-code/hooks/session-start.sh

@@ -0,0 +1,80 @@
+#!/usr/bin/env bash
+# Syntaur SessionStart Hook
+# (1) Merges the real Claude Code session_id + transcript_path into an
+#     EXISTING .syntaur/context.json. Never creates context.json — that would
+#     break grab-assignment's "context.json implies active assignment" semantic.
+# (2) Pre-registers a minimal row in the dashboard sessions table so
+#     SessionEnd's PATCH /status always has a row to target. Best-effort —
+#     silently ignores dashboard-unreachable.
+#
+# Reads JSON from stdin per Claude Code SessionStart contract:
+#   { "session_id": "...", "transcript_path": "...", "cwd": "...", ... }
+#
+# Always exits 0.
+
+set -o pipefail 2>/dev/null || true
+
+command -v jq >/dev/null 2>&1 || exit 0
+
+INPUT=$(cat)
+[ -z "$INPUT" ] && exit 0
+
+SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // empty' 2>/dev/null)
+TRANSCRIPT_PATH=$(printf '%s' "$INPUT" | jq -r '.transcript_path // empty' 2>/dev/null)
+CWD=$(printf '%s' "$INPUT" | jq -r '.cwd // empty' 2>/dev/null)
+
+[ -z "$SESSION_ID" ] && exit 0
+[ -z "$CWD" ] && exit 0
+
+CONTEXT_FILE="$CWD/.syntaur/context.json"
+
+# REQUIRED invariant: only operate on an EXISTING context file. If the current
+# cwd has no active Syntaur assignment, leave the filesystem untouched.
+[ ! -f "$CONTEXT_FILE" ] && exit 0
+
+# --- (1) Merge session fields into context.json.
+# Always replace both sessionId and transcriptPath together. If the incoming
+# transcript_path is empty, explicitly null the stored transcriptPath so a new
+# session never inherits a stale transcript path from the prior session.
+TMP="${CONTEXT_FILE}.tmp.$$"
+jq \
+  --arg sid "$SESSION_ID" \
+  --arg tp "$TRANSCRIPT_PATH" \
+  '. + {sessionId: $sid, transcriptPath: (if ($tp | length) > 0 then $tp else null end)}' \
+  "$CONTEXT_FILE" > "$TMP" 2>/dev/null \
+  && mv "$TMP" "$CONTEXT_FILE" 2>/dev/null \
+  || rm -f "$TMP"
+
+# --- (2) Best-effort pre-registration in the dashboard.
+# Read project/assignment context if present so the pre-registered row is
+# already linked. Upsert semantics on the server mean this is idempotent with
+# later /track-session or grab-assignment calls.
+MISSION_SLUG=$(jq -r '.projectSlug // empty' "$CONTEXT_FILE" 2>/dev/null)
+ASSIGNMENT_SLUG=$(jq -r '.assignmentSlug // empty' "$CONTEXT_FILE" 2>/dev/null)
+
+PORT="${SYNTAUR_DASHBOARD_PORT:-}"
+if [ -z "$PORT" ]; then
+  PORT=$(cat "$HOME/.syntaur/dashboard-port" 2>/dev/null || echo "4800")
+fi
+
+BODY=$(jq -cn \
+  --arg sid "$SESSION_ID" \
+  --arg tp "$TRANSCRIPT_PATH" \
+  --arg proj "$MISSION_SLUG" \
+  --arg assn "$ASSIGNMENT_SLUG" \
+  --arg path "$CWD" \
+  '{ agent: "claude", sessionId: $sid, path: $path }
+   + (if ($tp   | length) > 0 then {transcriptPath: $tp}    else {} end)
+   + (if ($proj | length) > 0 then {projectSlug: $proj}     else {} end)
+   + (if ($assn | length) > 0 then {assignmentSlug: $assn}  else {} end)' 2>/dev/null)
+
+if [ -n "$BODY" ]; then
+  # --max-time bounds the hook's wall-clock cost if the dashboard socket
+  # accepts but then hangs. The hook itself is registered with timeout: 5.
+  curl -sf --max-time 3 -X POST "http://127.0.0.1:${PORT}/api/agent-sessions" \
+    -H "Content-Type: application/json" \
+    -d "$BODY" \
+    -o /dev/null 2>/dev/null || true
+fi
+
+exit 0

package/platforms/claude-code/hooks/statusline.sh

@@ -0,0 +1,110 @@
+#!/usr/bin/env bash
+# Syntaur Claude Code statusLine.
+#
+# Renders a single line with:
+#   <branch> · <worktree-basename> · <assignment> · <sessionId-suffix>
+#
+# Reads JSON from stdin per Claude Code statusLine contract:
+#   { "session_id": "...", "cwd": "...", "workspace": { "current_dir": "..." }, ... }
+#
+# Empty segments are omitted. Never fails the terminal — always exits 0.
+
+set -o pipefail 2>/dev/null || true
+
+INPUT=$(cat)
+
+# Degrade cleanly if jq is unavailable.
+if ! command -v jq >/dev/null 2>&1; then
+  printf '%s' '(syntaur: jq missing)'
+  exit 0
+fi
+
+SESSION_ID=""
+CWD=""
+
+if [ -n "$INPUT" ]; then
+  SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // empty' 2>/dev/null)
+  CWD=$(printf '%s' "$INPUT" | jq -r '.workspace.current_dir // .cwd // empty' 2>/dev/null)
+fi
+
+# Fall back to the shell's CWD if the payload omits it.
+[ -z "$CWD" ] && CWD="$PWD"
+
+# --- Segment 1: branch ---
+BRANCH=""
+if [ -n "$CWD" ] && [ -d "$CWD" ]; then
+  BRANCH=$(git -C "$CWD" rev-parse --abbrev-ref HEAD 2>/dev/null)
+  if [ "$BRANCH" = "HEAD" ] || [ -z "$BRANCH" ]; then
+    SHORT=$(git -C "$CWD" rev-parse --short HEAD 2>/dev/null)
+    if [ -n "$SHORT" ]; then
+      BRANCH="detached@$SHORT"
+    else
+      BRANCH=""
+    fi
+  fi
+fi
+
+# --- Segment 2: worktree basename ---
+WORKTREE=""
+if [ -n "$CWD" ] && [ -d "$CWD" ]; then
+  WT_PATH=$(git -C "$CWD" rev-parse --show-toplevel 2>/dev/null)
+  if [ -n "$WT_PATH" ]; then
+    WORKTREE=$(basename "$WT_PATH")
+  fi
+fi
+
+# --- Segment 3: active syntaur assignment ---
+ASSIGNMENT=""
+CONTEXT_FILE="$CWD/.syntaur/context.json"
+if [ -f "$CONTEXT_FILE" ]; then
+  PROJECT_SLUG=$(jq -r '.projectSlug // empty' "$CONTEXT_FILE" 2>/dev/null)
+  ASSIGNMENT_SLUG=$(jq -r '.assignmentSlug // empty' "$CONTEXT_FILE" 2>/dev/null)
+  ASSIGNMENT_DIR=$(jq -r '.assignmentDir // empty' "$CONTEXT_FILE" 2>/dev/null)
+
+  TITLE=""
+  if [ -n "$ASSIGNMENT_DIR" ] && [ -f "$ASSIGNMENT_DIR/assignment.md" ]; then
+    TITLE=$(awk '/^title:/{sub(/^title:[[:space:]]*"?/,""); sub(/"?[[:space:]]*$/,""); print; exit}' "$ASSIGNMENT_DIR/assignment.md" 2>/dev/null)
+  fi
+
+  LABEL=""
+  if [ -n "$PROJECT_SLUG" ] && [ -n "$ASSIGNMENT_SLUG" ]; then
+    LABEL="$PROJECT_SLUG/$ASSIGNMENT_SLUG"
+  elif [ -n "$ASSIGNMENT_SLUG" ]; then
+    # Standalone assignment — assignmentSlug is the UUID folder name. Take the
+    # first 8 chars for terseness.
+    UUID_PREFIX="${ASSIGNMENT_SLUG:0:8}"
+    LABEL="standalone/$UUID_PREFIX"
+  fi
+
+  if [ -n "$LABEL" ] && [ -n "$TITLE" ]; then
+    ASSIGNMENT="$LABEL — $TITLE"
+  elif [ -n "$LABEL" ]; then
+    ASSIGNMENT="$LABEL"
+  fi
+fi
+
+# --- Segment 4: session id suffix ---
+SESSION_SUFFIX=""
+if [ -n "$SESSION_ID" ]; then
+  LEN=${#SESSION_ID}
+  if [ "$LEN" -gt 8 ]; then
+    SESSION_SUFFIX="…${SESSION_ID: -8}"
+  else
+    SESSION_SUFFIX="$SESSION_ID"
+  fi
+fi
+
+# --- Join segments with ' · ', suppressing empties. ---
+OUT=""
+for seg in "$BRANCH" "$WORKTREE" "$ASSIGNMENT" "$SESSION_SUFFIX"; do
+  if [ -n "$seg" ]; then
+    if [ -z "$OUT" ]; then
+      OUT="$seg"
+    else
+      OUT="$OUT · $seg"
+    fi
+  fi
+done
+
+printf '%s' "$OUT"
+exit 0

package/platforms/claude-code/references/file-ownership.md

@@ -7,8 +7,6 @@ Agents must NEVER modify these files:
 | File | Location |
 |------|----------|
 | `project.md` | `<project>/project.md` |
-| `agent.md` | `<project>/agent.md` |
-| `claude.md` | `<project>/claude.md` |
 
 ## Agent-Writable (YOUR assignment folder ONLY)
 
@@ -18,11 +16,25 @@ You may ONLY write to files inside your assigned assignment folder:
 |------|---------|
 | `assignment.md` | Assignment record, source of truth for state (includes `## Todos` checklist) |
 | `plan*.md` | Versioned implementation plans (optional, 0 or more: `plan.md`, `plan-v2.md`, ...) — each linked from a todo in `assignment.md` |
+| `progress.md` | Append-only timestamped progress log (newest first). Replaces the old `## Progress` body section. |
 | `scratchpad.md` | Working notes |
 | `handoff.md` | Append-only handoff log |
 | `decision-record.md` | Append-only decision log |
 
-Path pattern: `~/.syntaur/projects/<project>/assignments/<your-assignment>/`
+Path pattern (project-nested): `~/.syntaur/projects/<project>/assignments/<your-assignment>/`
+Path pattern (standalone): `~/.syntaur/assignments/<your-assignment-uuid>/`
+
+## CLI-Mediated Shared-Writable
+
+Do NOT edit these files directly. Use the listed CLI commands:
+
+| File | Mediator |
+|------|----------|
+| `comments.md` (any assignment) | `syntaur comment <slug-or-uuid> "body" [--type question\|note\|feedback] [--reply-to <id>]` |
+| `## Todos` in another assignment's `assignment.md` (cross-assignment request) | `syntaur request <source> <target> "text"` |
+| Question resolution | `PATCH /api/.../comments/:id/resolved` (dashboard) or toggle in dashboard UI |
+
+These are bounded exceptions to the single-writer rule for assignment folders — the CLI serializes writes to avoid conflicts.
 
 ## Shared-Writable (any agent or human)
 

package/platforms/claude-code/references/protocol-summary.md

@@ -1,5 +1,7 @@
 # Syntaur Protocol Summary
 
+Protocol version: **2.0**
+
 ## Directory Structure
 
 ```
@@ -13,12 +15,12 @@
       _index-plans.md        # Derived (read-only)
       _index-decisions.md    # Derived (read-only)
       _status.md             # Derived (read-only)
-      claude.md              # Human-authored: Claude-specific instructions (read-only)
-      agent.md               # Human-authored: universal agent instructions (read-only)
       assignments/
         <assignment-slug>/
           assignment.md      # Agent-writable: source of truth for state (includes ## Todos checklist)
           plan*.md           # Agent-writable: versioned implementation plans (optional, 0 or more: plan.md, plan-v2.md, ...)
+          progress.md        # Agent-writable, append-only: timestamped progress log
+          comments.md        # CLI-mediated: threaded questions/notes/feedback (via `syntaur comment`)
           scratchpad.md      # Agent-writable: working notes
           handoff.md         # Agent-writable: append-only handoff log
           decision-record.md # Agent-writable: append-only decision log
@@ -28,6 +30,15 @@
       memories/
         _index.md            # Derived (read-only)
         <memory-slug>.md     # Shared-writable
+  assignments/
+    <assignment-id>/         # Standalone assignments — folder named by UUID, `project: null`
+      assignment.md          # Same schema as project-nested, `slug` is display-only
+      plan*.md
+      progress.md
+      comments.md
+      scratchpad.md
+      handoff.md
+      decision-record.md
   playbooks/
     manifest.md              # Derived: playbook listing (read-only)
     <slug>.md                # User-authored: behavioral rules for agents
@@ -62,10 +73,13 @@
 ## Key Rules
 
 1. **Assignment frontmatter is the single source of truth** for all assignment state.
-2. **One folder per project**, one subfolder per assignment.
+2. **Project-nested assignments** live at `projects/<slug>/assignments/<aslug>/` (folder name = slug). **Standalone assignments** live at `assignments/<uuid>/` (folder name = UUID, `project: null`, slug display-only).
 3. **Derived files** (underscore-prefixed) are never edited manually.
 4. **Slugs** are lowercase, hyphen-separated.
-5. **Dependencies** are declared via `dependsOn` in assignment frontmatter.
+5. **Dependencies** are declared via `dependsOn` in assignment frontmatter. Only valid within the same project — standalone assignments cannot declare `dependsOn`.
 6. An assignment cannot transition from `pending` to `in_progress` while any dependency is not `completed`.
 7. **Playbooks** in `~/.syntaur/playbooks/` define behavioral rules agents must follow. Read `manifest.md` for a summary, then read each referenced playbook before starting work.
-8. **Todos** in the `## Todos` section of `assignment.md` are an informal markdown checklist. Items may be simple tasks or link to plan files. When a plan is superseded, mark the old todo: `- [x] ~~Execute [plan](./plan.md)~~ (superseded by plan-v2)` — never delete it.
+8. **Todos** in the `## Todos` section of `assignment.md` are an informal markdown checklist. Items may be simple tasks or link to plan files. When a plan is superseded, mark the old todo: `- [x] ~~Execute [plan](./plan.md)~~ (superseded by plan-v2)` — never delete it. `## Todos` is also the landing spot for cross-assignment requests via `syntaur request`.
+9. **Progress** is appended to `progress.md` as timestamped entries (newest first). Do not add a `## Progress` section to `assignment.md`.
+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.
+11. **Cross-assignment work** is requested via `syntaur request <source> <target> "text"` — appends to the target's `## Todos` annotated `(from: <source>)`.

package/platforms/claude-code/skills/complete-assignment/SKILL.md

@@ -51,6 +51,20 @@ If any acceptance criteria are unmet OR any todo is still `- [ ]` and not supers
 
 If the user says no, stop.
 
+## Step 2.5: Append a Final Progress Entry
+
+Before writing the handoff, append a final entry to `<assignmentDir>/progress.md` summarizing what was completed. The entry goes at the **top** of the body (reverse-chron order) under a new `## <RFC 3339 timestamp>` heading:
+
+```markdown
+## <ISO 8601 timestamp>
+
+<One paragraph summarizing the final state of work: what was implemented, what verifications passed, and any deliberate scope exclusions.>
+```
+
+Update `progress.md`'s frontmatter: bump `entryCount` and set `updated` to the current timestamp.
+
+Do NOT add a `## Progress` section to `assignment.md` — progress entries live exclusively in `progress.md` as of protocol v2.0.
+
 ## Step 3: Write Handoff Entry
 
 Read `<assignmentDir>/handoff.md` to see its current content and frontmatter.

package/platforms/claude-code/skills/create-assignment/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: create-assignment
 description: Create a new Syntaur assignment within a project (or as a one-off)
-argument-hint: <title> --project <slug> [--priority <level>] [--depends-on <slugs>] [--one-off]
+argument-hint: <title> --project <slug> [--priority <level>] [--depends-on <slugs>] [--type <type>] [--one-off]
 allowed-tools:
   - Bash
   - Read
@@ -18,10 +18,11 @@ The user provided: $ARGUMENTS
 Parse the arguments:
 - First argument (required): the assignment title (e.g., `"Add login endpoint"`)
 - `--project <slug>` (required unless `--one-off`): the project to add the assignment to
-- `--one-off` (optional): create a standalone project+assignment in one step
+- `--one-off` (optional): create a **standalone** assignment at `~/.syntaur/assignments/<uuid>/` with `project: null`. Folder is named by UUID; `slug` is display-only. `--depends-on` is not permitted for standalone assignments.
 - `--slug` (optional): override the auto-generated assignment slug
 - `--priority` (optional): `low`, `medium` (default), `high`, or `critical`
-- `--depends-on` (optional): comma-separated list of assignment slugs this depends on
+- `--type` (optional): classification such as `feature`, `bug`, `refactor`, `research`, `chore`. Defaults to `feature`. When `~/.syntaur/config.md` defines `types.definitions`, the CLI validates against that list.
+- `--depends-on` (optional, project-nested only): comma-separated list of assignment slugs this depends on
 - `--dir` (optional): override the default project directory
 
 If no title was provided, ask the user what the assignment should be called.
@@ -35,13 +36,13 @@ If there is no active context and no project flag, ask the user which project to
 Build the command from the parsed arguments. Use `dangerouslyDisableSandbox: true` since the CLI writes to `~/.syntaur/` which is outside the project sandbox.
 
 ```bash
-syntaur create-assignment "<title>" --project <slug> [--slug <slug>] [--priority <level>] [--depends-on <slugs>] [--dir <path>]
+syntaur create-assignment "<title>" --project <slug> [--slug <slug>] [--priority <level>] [--depends-on <slugs>] [--type <type>] [--dir <path>]
 ```
 
-Or for one-off:
+Or for one-off (standalone at `~/.syntaur/assignments/<uuid>/`):
 
 ```bash
-syntaur create-assignment "<title>" --one-off [--slug <slug>] [--priority <level>] [--dir <path>]
+syntaur create-assignment "<title>" --one-off [--slug <slug>] [--priority <level>] [--type <type>] [--dir <path>]
 ```
 
 If the command fails (e.g., project not found, slug collision), report the error and suggest fixes.
@@ -57,9 +58,10 @@ cat ~/.syntaur/projects/<project-slug>/assignments/<assignment-slug>/assignment.
 ## Step 3: Guide Next Steps
 
 Tell the user:
-- The assignment was created with its slug, priority, and location
-- List the files created (assignment.md, scratchpad.md, handoff.md, decision-record.md). Note that `plan.md` is NOT scaffolded — plan files are optional and created on demand by `/plan-assignment`.
+- The assignment was created with its slug, priority, type, and location. For standalone assignments, the location is `~/.syntaur/assignments/<uuid>/` — note the UUID (not slug) is the folder name.
+- List the files created: `assignment.md`, `progress.md`, `comments.md`, `scratchpad.md`, `handoff.md`, `decision-record.md`. `plan.md` is NOT scaffolded — plan files are optional and created on demand by `/plan-assignment`.
+- Remind the user: `progress.md` is where timestamped progress entries go (not `assignment.md`), and `comments.md` is written only via `syntaur comment <slug-or-uuid> "body" --type question|note|feedback`.
 - Suggest they edit `assignment.md` to fill in the objective, acceptance criteria, context, and any initial todos. The `## Todos` section accepts simple tasks or markdown links to plan files.
 - Or suggest running `/plan-assignment` after grabbing — it creates a plan file and auto-appends a linked todo to `## Todos`.
-- If dependencies were set, note them
-- Suggest running `/grab-assignment <project-slug> <assignment-slug>` to claim and start working on it
+- If dependencies were set, note them. (Standalone assignments cannot declare dependencies.)
+- Suggest running `/grab-assignment <project-slug> <assignment-slug>` (or `/grab-assignment --id <uuid>` for standalone) to claim and start working on it.

package/platforms/claude-code/skills/grab-assignment/SKILL.md

@@ -27,8 +27,9 @@ Parse the arguments:
 ## Pre-flight Check
 
 1. Check if `.syntaur/context.json` already exists in the current working directory.
-   - If it exists, read it and warn the user: "You already have an active assignment: `<assignmentSlug>` in project `<projectSlug>`. Grabbing a new assignment will replace this context. Proceed?"
+   - If it exists AND contains BOTH `projectSlug` and `assignmentSlug`, read it and warn the user: "You already have an active assignment: `<assignmentSlug>` in project `<projectSlug>`. Grabbing a new assignment will replace this context. Proceed?"
    - If the user says no, stop.
+   - If the file exists but only has session fields (`sessionId`, `transcriptPath`) and no project/assignment, do NOT warn — that context was populated by the SessionStart hook and is not an "active assignment" marker. Proceed silently and merge new assignment fields in Step 5.
 
 ## Step 1: Discover the Project
 
@@ -113,15 +114,17 @@ workspace:
   worktreePath: /absolute/path/to/cwd
 ```
 
-## Step 5: Create Context File
+## Step 5: Create or Merge Context File
 
-Write `.syntaur/context.json` in the current working directory with the assignment context. First ensure the directory exists:
+Merge assignment context into `.syntaur/context.json`. Do NOT overwrite: if the file already exists (e.g., the SessionStart hook populated `sessionId` + `transcriptPath`), preserve those fields.
+
+First ensure the directory exists:
 
 ```bash
 mkdir -p .syntaur
 ```
 
-Then write the JSON file with this structure:
+Prepare the assignment payload:
 
 ```json
 {
@@ -136,26 +139,38 @@ Then write the JSON file with this structure:
 }
 ```
 
+Merge it on top of whatever context.json already contains:
+
+```bash
+if [ -f .syntaur/context.json ]; then
+  jq --slurpfile new <(echo "$NEW_CONTEXT_JSON") '. + $new[0]' .syntaur/context.json > .syntaur/context.json.tmp \
+    && mv .syntaur/context.json.tmp .syntaur/context.json
+else
+  echo "$NEW_CONTEXT_JSON" > .syntaur/context.json
+fi
+```
+
+This preserves any `sessionId` / `transcriptPath` the SessionStart hook wrote, while layering assignment fields on top.
+
 Use absolute paths (expand `~` to the actual home directory). Note: `workspace.repository` may be a remote URL (e.g., `https://github.com/...`) -- only use it as `workspaceRoot` if it starts with `/` (local path). If it is a URL, set `workspaceRoot` to the current working directory.
 
 **IMPORTANT:** The `workspaceRoot` must NEVER be null when the agent will be writing code. If no workspace was configured, default to the current working directory.
 
 ## Step 5.5: Register Agent Session
 
-After creating the context file, register this session in the project's agent session log so it appears in the dashboard.
+After merging context, register this session in the dashboard.
 
-1. Find the current Claude Code session ID by reading from `~/.claude/sessions/`. These are JSON files keyed by PID containing `sessionId`, `cwd`, etc. Find the most recently modified file whose `cwd` matches the current working directory:
-```bash
-ls -t ~/.claude/sessions/*.json | head -5
-```
-Read the most recent file(s) and find the one whose `cwd` matches `$(pwd)`. Extract the `sessionId` field — this is the real Claude Code session ID that can be used with `claude --resume <sessionId>` to resume this exact conversation.
+1. **Source the real Claude session_id + transcript_path.** In priority order:
+   1. If `.syntaur/context.json` already has `sessionId` (SessionStart hook populated it), use that ID and read `transcriptPath` from the same file.
+   2. Otherwise, fall back to `~/.claude/sessions/*.json`: `ls -t ~/.claude/sessions/*.json | head -5`, read each, and pick the most recently modified entry whose `cwd` matches `$(pwd)`. Extract `sessionId`. The transcript path for Claude Code lives at `~/.claude/projects/<encoded-cwd>/<sessionId>.jsonl` — construct that path if you need it.
+   3. If neither source yields a real ID, DO NOT synthesize one. Abort with: "Could not resolve a real Claude Code session id. Restart the Claude session so the SessionStart hook can populate `.syntaur/context.json`, or run `/rename <assignment-slug>` and retry."
 
-If you cannot find a matching session file (e.g., no file matches the cwd, or the sessions directory is empty), ask the user to run `/rename <assignment-slug>` to name the current session after the assignment. Then store the assignment slug as the session name in context.json (`"sessionName": "<assignment-slug>"`) instead of `sessionId`. The user can later resume with `claude --resume <assignment-slug>`.
+2. **Merge `sessionId` and `transcriptPath` back into context.json** (safe even if already present — jq merge is idempotent).
 
-2. Run the track-session command (use `dangerouslyDisableSandbox: true` since it writes to `~/.syntaur/`):
-```bash
-syntaur track-session --project <projectSlug> --assignment <assignmentSlug> --agent claude --session-id <claude-session-id> --path $(pwd)
-```
+3. **Run the track-session CLI** (use `dangerouslyDisableSandbox: true` since it writes to `~/.syntaur/`). Both `--session-id` and real path are required:
+   ```bash
+   syntaur track-session --project <projectSlug> --assignment <assignmentSlug> --agent claude --session-id <real-session-id> --transcript-path <transcript-path> --path $(pwd)
+   ```
 
 3. Update the `.syntaur/context.json` context file to include the session ID. Add `"sessionId": "<claude-session-id>"` to the JSON object you wrote in Step 5.
 

package/platforms/claude-code/skills/plan-assignment/SKILL.md

@@ -46,13 +46,20 @@ For each file found, read it and follow its directives. Playbooks may contain ru
 
 Read the following files to understand the assignment:
 
-1. Read `<assignmentDir>/assignment.md` -- extract the objective, acceptance criteria, context section, and any Q&A
-2. Read `<projectDir>/agent.md` -- extract conventions and boundaries
-3. Read `<projectDir>/claude.md` if it exists -- extract Claude-specific instructions
-4. Read `<projectDir>/project.md` -- extract the project goal for broader context
-
-If the assignment has dependencies (`dependsOn` in frontmatter), read the handoff.md from each dependency's assignment folder for integration context:
+1. Read `<assignmentDir>/assignment.md` -- extract the objective, acceptance criteria, context section, and the `## Todos` list
+2. Read `<assignmentDir>/comments.md` if it exists -- inherited questions, notes, and feedback
+3. Read `<projectDir>/project.md` -- extract the project goal for broader context
+4. Read `<projectDir>/manifest.md` -- navigation index for the project
+
+Per-project `agent.md` and `claude.md` were removed in v0.2.0. The agent-level
+conventions now live in the repo root `CLAUDE.md` / `AGENTS.md` and in
+`~/.syntaur/playbooks/`, which Step 1.5 already loaded.
+
+If the assignment has dependencies (`dependsOn` in frontmatter), read each
+dependency's `handoff.md` and `decision-record.md` for integration context and
+upstream decisions:
 - `<projectDir>/assignments/<dep-slug>/handoff.md`
+- `<projectDir>/assignments/<dep-slug>/decision-record.md`
 
 ## Step 3: Explore Workspace (if set)
 
@@ -144,5 +151,6 @@ After writing the plan:
 
 **Remind the agent about recordkeeping during implementation:**
 - Check off acceptance criteria in `assignment.md` as each one is completed, not in a batch at the end
-- Update the `## Progress` section in `assignment.md` after each meaningful milestone
-- The assignment file is a live document — it should reflect current state at all times
+- Append timestamped milestones to `progress.md` (separate append-only file) — not to `assignment.md`
+- Use `syntaur comment <slug-or-uuid> "body" --type note|question|feedback` to add a comment to `comments.md`
+- `assignment.md` is a live document — keep its status, todos, and acceptance checkboxes reflecting current state at all times

package/platforms/claude-code/skills/syntaur-protocol/SKILL.md

@@ -12,21 +12,26 @@ You are working within the Syntaur protocol. Follow these rules at all times.
 
 You MUST respect file ownership boundaries. Violations will be blocked by the PreToolUse hook.
 
-### Files you may WRITE:
+### Files you may WRITE directly:
 1. **Your assignment folder** -- only the assignment you are currently working on:
-   - `assignment.md`, `plan*.md` (0 or more versioned plan files), `scratchpad.md`, `handoff.md`, `decision-record.md`
-   - Path: `~/.syntaur/projects/<project>/assignments/<your-assignment>/`
+   - `assignment.md`, `plan*.md` (0 or more versioned plan files), `progress.md`, `scratchpad.md`, `handoff.md`, `decision-record.md`
+   - Path (project-nested): `~/.syntaur/projects/<project>/assignments/<your-assignment>/`
+   - Path (standalone): `~/.syntaur/assignments/<your-assignment-uuid>/` — folder named by UUID, `project: null`, `slug` display-only
 2. **Shared resources and memories** at the project level:
    - `~/.syntaur/projects/<project>/resources/<slug>.md`
    - `~/.syntaur/projects/<project>/memories/<slug>.md`
 3. **Your workspace** -- source code files within the workspace defined in your assignment's frontmatter (`workspace.worktreePath` or `workspace.repository`)
 4. **Context file** -- `.syntaur/context.json` in the current working directory
 
+### Files written only via CLI (never edit directly):
+- `comments.md` (any assignment) — use `syntaur comment <slug-or-uuid> "body" --type question|note|feedback [--reply-to <id>]`. Never edit directly. Questions carry a `resolved` flag toggled in the dashboard.
+- Another assignment's `## Todos` section — use `syntaur request <target> "text"` to append a todo annotated `(from: <source>)`.
+
 ### Files you must NEVER write:
-1. `project.md`, `agent.md`, `claude.md` -- human-authored, read-only
+1. `project.md` -- human-authored, read-only
 2. `manifest.md` -- derived, rebuilt by tooling
 3. Any file prefixed with `_` (`_index-*.md`, `_status.md`) -- derived
-4. Other agents' assignment folders
+4. Other agents' assignment folders (except via the CLI-mediated channels above)
 5. Any files outside your workspace boundary
 
 ## Current Assignment Context
@@ -46,7 +51,7 @@ For detailed protocol information, read these files:
 
 ## Lifecycle Commands
 
-Use the `syntaur` CLI for state transitions. Available commands:
+Use the `syntaur` CLI for state transitions and coordination:
 - `syntaur assign <slug> --agent <name> --project <project>` -- set assignee
 - `syntaur start <slug> --project <project>` -- pending -> in_progress
 - `syntaur review <slug> --project <project>` -- in_progress -> review
@@ -54,6 +59,9 @@ Use the `syntaur` CLI for state transitions. Available commands:
 - `syntaur block <slug> --project <project> --reason <text>` -- block an assignment
 - `syntaur unblock <slug> --project <project>` -- unblock
 - `syntaur fail <slug> --project <project>` -- mark as failed
+- `syntaur create-assignment "<title>" [--type <type>] [--project <slug> | --one-off]` -- create project-nested or standalone assignment
+- `syntaur comment <slug-or-uuid> "body" --type question|note|feedback [--reply-to <id>]` -- append to `comments.md`
+- `syntaur request <target> "text" [--from <source>]` -- append a todo to another assignment's `## Todos`
 
 ## Troubleshooting
 
@@ -69,8 +77,10 @@ ls ~/.syntaur/playbooks/*.md 2>/dev/null
 
 ## Conventions
 
-- Assignment frontmatter is the single source of truth for state
-- Slugs are lowercase, hyphen-separated
-- Always read `agent.md` and `claude.md` at the project level before starting work
-- Add unanswered questions to the Q&A section of assignment.md (do not set status to blocked for questions)
-- Commit frequently with messages referencing the assignment slug
+- Assignment frontmatter is the single source of truth for state. `project` is the containing project slug (`null` for standalone); `type` is a classification validated against `config.md` `types.definitions` when present.
+- Slugs are lowercase, hyphen-separated. For standalone assignments, the folder is named by UUID; `slug` is display-only.
+- Always read `project.md` at the project level (when project-nested) before starting work.
+- Append timestamped entries to `progress.md` as work lands — do NOT add a `## Progress` section to `assignment.md`.
+- Record questions/notes/feedback via `syntaur comment` — never edit `comments.md` directly. Do NOT set status to blocked for questions.
+- Use `syntaur request` to route work to another assignment.
+- Commit frequently with messages referencing the assignment slug.

package/platforms/codex/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "syntaur",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Run Syntaur project and assignment workflows from Codex, including claiming work, planning, completing handoffs, session tracking, and write-boundary enforcement.",
   "author": {
     "name": "Brennen"