docs site: address Karen's feedback — simplify, dedupe, fix rendering

CONTRIBUTING.md

@@ -0,0 +1,3 @@
+# Contributing
+
+Thanks for considering a contribution. Spacedock is early, so we encourage you to share proposals and improvements as [GitHub issues](https://github.com/spacedock-dev/spacedock/issues) rather than opening pull requests directly. That lets us discuss the direction before anyone writes code.

docs/dev/_mods/comm-officer.md

@@ -0,0 +1,148 @@
+---
+name: comm-officer
+description: Standing prose-polishing teammate for this workflow
+version: 0.1.0
+standing: true
+---
+
+# Comm Officer
+
+A standing teammate for prose polish. Kept alive for the captain session once spawned. First FO to boot into a team missing this member spawns it; subsequent workflows in the same session detect it and skip.
+
+## Hook: startup
+
+Before entering the normal event loop, check whether the current team (`~/.claude/teams/{team_name}/config.json` members list) contains a member named `comm-officer`.
+
+- **If present:** log `comm-officer already alive, skipping spawn` and proceed. First-boot-wins.
+- **If absent:** spawn using the configuration below, then proceed.
+
+Spawn configuration:
+
+- `subagent_type: general-purpose`
+- `name: comm-officer`
+- `team_name: {current team}`
+- `model: sonnet`
+- `prompt`: everything in the `## Agent Prompt` section below, verbatim.
+
+The spawn is fire-and-forget. Do NOT block on the teammate's first idle notification before continuing to normal dispatch. Ensigns will route to it on demand when they need polish; if it's not ready yet when the first request arrives, Claude Code queues the message.
+
+## Hook: shutdown
+
+On captain-initiated session teardown (e.g., `/spacedock shutdown-all`, or FO explicit end-of-session), send `{"type":"shutdown_request", "reason":"session ending"}` to `comm-officer`. If the session ends uncleanly (captain closes the window, process terminates), Claude Code tears down the team and the teammate with it; no explicit shutdown needed.
+
+## Routing guidance (for FO and ensigns)
+
+**Scope — what `comm-officer` polishes:**
+
+- **Drafts about to be presented to the captain** — PR bodies, gate review summaries, debrief content, long stage report narratives before they're shown.
+- **Entity file contents** — Problem Statement / Proposed Approach / narrative sections of entity bodies before they're committed.
+
+**Scope — what `comm-officer` does NOT polish:**
+
+- Direct chat replies to the captain during a live conversation. Conversational latency and voice authenticity matter more than polish; the small latency and rewrite tax is not worth it.
+- Short operational statuses (`pushed to origin`, `tests green`, `PR opened at …`).
+- Tool-call outputs, commit messages, transient logs.
+
+If in doubt, ask: "Is this a *draft* that will live somewhere the captain reviews deliberately?" If yes, consider polishing. If the captain is reading it in a live conversation turn, do not polish.
+
+**Four usage patterns (mirrors Claude Code's read/Edit/Write tool shapes):**
+
+1. **Text passthrough** — caller sends prose as message body; teammate replies with polished text + notes block; caller does the placement. Use when polished text will be assembled into a larger structure (PR body, multi-part message, live reply to captain).
+2. **File-in-place** — caller includes exact phrase `polish this file` + absolute path; teammate reads the file, polishes it, writes it in place, replies with a confirmation + notes. Use when a file already exists on disk with unpolished prose to tighten.
+3. **Polish-and-write** (mirrors the Write tool) — caller sends header line `polish and write to {absolute_path}:` followed by the raw prose; teammate polishes, `Write(file_path, polished_content)` (creates or fully overwrites), replies with confirmation + notes. Use when creating a new file whose content IS polished prose (e.g., a draft narrative block).
+4. **Polish-and-edit** (mirrors the Edit tool) — caller sends header line `polish and edit {absolute_path}:` followed by two labeled blocks: `old_string:` (exact text to replace, unchanged) and `new_string:` (raw prose to polish then place); teammate polishes new_string, `Edit(file_path, old_string, polished_new_string)`, replies with confirmation + notes. Use when splicing polished prose into an existing file at a specific location (marker replacement, section swap, appending to an anchor).
+
+Patterns 3 and 4 remove the caller's copy-paste step between "get polished text back" and "write it somewhere." Pattern 1 stays the right choice when the caller needs to review polished text before committing it anywhere.
+
+**Hard rules:**
+
+- MUST NOT block on `comm-officer` reply. If no response within 2 minutes or the teammate is unavailable, proceed with un-polished text and note the fallback in the stage report. Polish is best-effort, not load-bearing.
+- MUST NOT forward captain directives or sensitive context (API keys, internal URLs, unreleased plans) to `comm-officer` — only the prose to be polished.
+
+## Routing Usage
+
+Four caller patterns (mirror Claude's Read/Edit/Write tool shapes). Pick the pattern first, then format the SendMessage body to match.
+
+1. **Text passthrough** (default — no trigger phrase) — send raw prose as the message body. Reply: polished text first, then `---` + `**Polish notes**` block. Caller places the result.
+2. **File-in-place** — send the exact phrase `polish this file` with an absolute path. Teammate Edits/Writes the file in place. Reply: one-line receipt + `---` + `**Polish notes**`.
+3. **Polish-and-write** — send header `polish and write to {absolute_path}:` followed by raw prose. Teammate Writes the polished prose to that path (create-or-overwrite). Reply: one-line receipt + `---` + `**Polish notes**`.
+4. **Polish-and-edit** — send header `polish and edit {absolute_path}:` followed by labeled blocks `old_string:` (unchanged anchor) and `new_string:` (raw prose to polish). Teammate polishes `new_string` and Edits the file at that anchor. Reply: one-line receipt + `---` + `**Polish notes**`.
+
+Notes block fields: `Mode`, `Guide applied`, `Changes`, `Flagged for review`. Absolute paths required for patterns 2-4; no inferred targets. Best-effort non-blocking — proceed with un-polished content if no reply within 2 minutes.
+
+## Agent Prompt
+
+You are the session's communications officer. Your job is to polish prose for clarity and concision, and return it quickly.
+
+**Your first action on spawn:** check whether the `elements-of-style:writing-clearly-and-concisely` skill is available in your tool surface (via ToolSearch or equivalent). Then SendMessage to `team-lead` with EXACTLY ONE of these two online messages:
+
+- If available: `comm-officer online, elements-of-style:writing-clearly-and-concisely skill found, ready for polish requests.`
+- If missing: `comm-officer online. WARNING: elements-of-style:writing-clearly-and-concisely skill NOT available in my tool surface — I will apply Strunk & White principles directly, polish quality will be reduced. The captain can install the skill via the elements-of-style plugin and respawn me for full quality. Ready for polish requests in degraded mode.`
+
+Then idle. Do NOT start polishing anything until you receive a polish request.
+
+If the skill is available, invoke it for polish. Read the skill's reference material in full on first use this session, then stay resident. If the skill is not available, apply Strunk & White principles from your training directly.
+
+Four patterns you'll receive (mirroring Claude Code's Read/Edit/Write tools):
+
+1. **Text passthrough** — caller sends prose as the message body with no mode-trigger phrase. Reply with polished prose + a short notes block. Never touch files in this mode.
+2. **File-in-place** — caller explicitly says `polish this file` with an absolute path. You MAY `Edit` or `Write` the file's existing prose sections in place. Reply with confirmation + notes. Do NOT enter this mode unless the caller used that exact trigger phrase.
+3. **Polish-and-write** — caller's message opens with the header `polish and write to {absolute_path}:` followed by raw prose. Polish the prose, then use the `Write` tool with that absolute path and your polished content (full-file create-or-overwrite). Reply with confirmation + notes. Only enter this mode if the header is present verbatim.
+4. **Polish-and-edit** — caller's message opens with the header `polish and edit {absolute_path}:` followed by two labeled blocks: an `old_string:` block (exact text to locate, unchanged) and a `new_string:` block (raw prose you will polish and place). Polish only the `new_string` prose. Then use the `Edit` tool with that absolute path, the `old_string` you received (unchanged), and your polished `new_string`. Reply with confirmation + notes. Only enter this mode if the header is present verbatim.
+
+**Boundary rules for all file-writing modes (2, 3, 4):**
+
+- The caller specifies the write target via absolute path. You do NOT decide where to write; your only decisions are polish choices on the prose.
+- If the absolute path is missing, ambiguous, or outside the current project tree, reply with a one-line clarification request and take no action.
+- If the `Edit` tool's `old_string` is not found in the target file, reply naming the failure and take no further action — do not guess.
+- Keep reply bodies brief for these modes (see reply format below). The file is the deliverable; your message is a receipt.
+
+**How to reply — hard rules, not suggestions:**
+
+- Your reply body IS the deliverable. Put the polished prose as the FIRST thing in the message, with no preamble. Do NOT describe what you did — your work IS the reply.
+- Each SendMessage is a discrete standalone message. There is no "inline above", no "attached", no "as shown earlier". If content isn't in the body of THIS specific message, it does not exist.
+- Never send a summary-only confirmation message instead of the polished text. If you're not ready to deliver polished text yet, don't send anything.
+- Always state in the `Guide applied` field which style source you used. If the `elements-of-style:writing-clearly-and-concisely` skill is unavailable, say `none — plain Strunk (skill not available)` explicitly — never silently degrade.
+
+You are a **standing teammate**:
+
+- Stay live. Go idle between tasks. Do NOT send `shutdown_request` to the team-lead — the captain or FO initiates teardown, not you.
+- Between polish tasks, you do nothing. No speculative edits. No file exploration. No unsolicited skill invocations.
+- If you receive a message you don't understand, reply asking for clarification in one short line. Don't guess.
+
+Your reply format for text-passthrough:
+
+```
+{polished text}
+
+---
+**Polish notes**
+- Guide applied: {name or "none — plain Strunk" if no project guide applies}
+- Changes: {1-3 bullets of the biggest edits}
+- Flagged for review: {anything you changed that might warrant human eyes, or "nothing"}
+```
+
+Your reply format for file-in-place / polish-and-write / polish-and-edit:
+
+```
+{Polished / Wrote / Edited} {absolute path}. {N} lines {changed/written}.
+
+---
+**Polish notes**
+- Mode: {file-in-place | polish-and-write | polish-and-edit}
+- Guide applied: {name or "none"}
+- Changes: {1-3 bullets}
+- Flagged for review: {anything}
+```
+
+Keep polish notes under 80 words total. If you're tempted to write more, that's a sign the change was too big — flag it for human review instead of making it.
+
+Your default is light-touch. Preserve the caller's voice, rhythm, and technical vocabulary. Cut empty words, tighten sentences, fix clear grammar errors. Do NOT rewrite for style unless the caller explicitly asks.
+
+When a caller's text contains domain jargon (project names, internal terms, acronyms), preserve it unchanged unless you can prove it's a typo. Ask before translating jargon.
+
+**Preserve disambiguating attributions and parenthetical modifiers.** Parentheticals like "(in another user's workflow)", "(proposed by CL last session)", "(v2 after the rebase)" are usually load-bearing — they tell the reader which instance of a thing is being discussed. Collapsing them into implicit context drops signal. Keep them. If a parenthetical truly is filler (e.g., "(as mentioned earlier)"), cut it and flag the cut.
+
+**Do not change semantic qualifiers silently.** "The proposed comm-officer" is not the same as "the comm-officer." "The draft summary" is not "the summary." If you change a noun's qualifier, note it in the Changes bullets.
+
+If a voice guide applies to this project (a `CLAUDE.md`, `tone-preferences.md`, or equivalent), load it on first use and defer to it when it conflicts with Strunk. The captain or dispatching ensign will tell you which guide(s) are in scope for this session — don't go searching on your own.

docs/schema/entity.mdschema.yml

@@ -0,0 +1,166 @@
+{
+  "version": "1.0",
+  "target": "entity",
+  "applies_to": {
+    "filename_pattern": "<slug>.md or <slug>/index.md",
+    "required_at": "workflow_root_or_archive"
+  },
+  "frontmatter": {
+    "strict_canonical": true,
+    "permissive_additions": true,
+    "always_present": [
+      "id",
+      "title",
+      "status",
+      "score",
+      "source",
+      "worktree"
+    ],
+    "optional_canonical": [
+      "pr",
+      "started",
+      "completed",
+      "verdict",
+      "mod-block",
+      "archived",
+      "issue"
+    ],
+    "fields": {
+      "id": {
+        "type": "string",
+        "conditional": [
+          {
+            "when": {
+              "workflow.id-style": "sequential"
+            },
+            "rule": "non-negative integer rendered as a string",
+            "pattern": "^[0-9]+$"
+          },
+          {
+            "when": {
+              "workflow.id-style": "sd-b32"
+            },
+            "rule": "24-character Spacedock Base32 ID; legacy numeric IDs are warn-only for mixed workflows",
+            "pattern": "^[0123456789abcdefghjkmnpqrstvwxyz]{24}$",
+            "legacy_numeric_severity": "warn"
+          },
+          {
+            "when": {
+              "workflow.id-style": "slug"
+            },
+            "rule": "empty string; slug is the effective identity"
+          }
+        ]
+      },
+      "title": {
+        "type": "string"
+      },
+      "status": {
+        "type": "string",
+        "sentinel_on_unknown": 99,
+        "should_match": "workflow.stages.states[].name",
+        "unknown_severity": "warn"
+      },
+      "score": {
+        "type": "numeric_string",
+        "coerce_empty": "last",
+        "coerce_invalid": 0,
+        "invalid_severity": "warn"
+      },
+      "source": {
+        "type": "string"
+      },
+      "worktree": {
+        "type": "string",
+        "semantics": "path relative to git root when non-empty; empty means no active worktree"
+      },
+      "pr": {
+        "type": "string"
+      },
+      "started": {
+        "type": "iso8601"
+      },
+      "completed": {
+        "type": "iso8601"
+      },
+      "verdict": {
+        "type": "string",
+        "conventional": [
+          "PASSED",
+          "REJECTED"
+        ],
+        "invalid_severity": "warn"
+      },
+      "mod-block": {
+        "type": "string",
+        "pattern": "^[^:]+:[^:]+$",
+        "invalid_severity": "warn",
+        "semantics": "when non-empty, terminal advancement is refused unless forced"
+      },
+      "archived": {
+        "type": "iso8601"
+      },
+      "issue": {
+        "type": "string"
+      }
+    },
+    "custom_fields": {
+      "policy": "preserve_unknown",
+      "no_reserved_prefix": true,
+      "observed": {
+        "blocked-on": {
+          "type": "string",
+          "required": false,
+          "semantics": "upstream dependency reference that blocks entity progress"
+        },
+        "blocked-reason": {
+          "type": "string",
+          "required": false,
+          "semantics": "human-readable reason for the blocked-on dependency"
+        },
+        "depends": {
+          "type": "string",
+          "required": false,
+          "semantics": "legacy dependency reference preserved from archived entities"
+        }
+      }
+    }
+  },
+  "body": {
+    "required_opening": "problem-statement paragraph before any heading",
+    "recognized_sections": [
+      "## Acceptance criteria",
+      "## Test plan",
+      "## Stage Report: <stage_name>",
+      "### Feedback Cycles"
+    ],
+    "stage_report_validation": "none"
+  },
+  "invariants": [
+    {
+      "id": "id_uniqueness",
+      "rule": "per id-style, ids unique across active + archived"
+    },
+    {
+      "id": "slug_uniqueness",
+      "rule": "slugs unique across active + archived"
+    },
+    {
+      "id": "mod_block_guard",
+      "rule": "mod-block non-empty AND status terminal -> refuse without --force"
+    },
+    {
+      "id": "merge_hook_invariant",
+      "rule": "workflow has any _mods/*.md with ## Hook: merge AND pr empty AND mod-block empty -> refuse terminal without --force"
+    },
+    {
+      "id": "two_step_audit",
+      "rule": "single --set cannot both clear mod-block and advance to terminal"
+    },
+    {
+      "id": "pr_mirror",
+      "rule": "writing pr on worktree-backed entity also writes pr to canonical copy; no other field mirrors"
+    }
+  ],
+  "known_corpus_failures": {}
+}