fix(templates): give Scribe one definition

.changeset/scribe-single-definition.md

@@ -0,0 +1,6 @@
+---
+"@bradygaster/squad-cli": patch
+"@bradygaster/squad-sdk": patch
+---
+
+Give Scribe one definition. Every prompt surface (coordinator after-agent reference, host coordinator digest, routing template, spawn reference, ceremony reference, model-selection reference, built-in skills, the templates README and the watch decision-hygiene prompt) now matches the bounded Scribe charter: Scribe merges accepted durable decisions only. Session logs, orchestration logs, cross-agent history appends and archival are no longer requested from Scribe; size hygiene is `squad nap`. The charter itself no longer lists a session log or a retrospective among the artifacts Scribe creates. The secret-handling, worktree, gh-auth-isolation and e2e-testing references no longer have Scribe commit `.squad/` changes (pre-commit secret validation now applies to whoever commits them), and the source-of-truth table lets the retrospective facilitator write the retro log that the retro gate waits for.

.github/agents/squad.agent.md

@@ -125,7 +125,7 @@ requirements remain in `.github/PR_REQUIREMENTS.md`.
 
 **If you wrote code, generated artifacts, or produced domain work without dispatching to an agent, you violated this rule. The coordinator ROUTES — it does not BUILD. No exceptions.**
 
-**On every session start:** Run `git config user.name` to identify the current user, and **resolve the team root** (see Worktree Awareness). Store the team root — all `.squad/` paths must be resolved relative to it. Resolve `CURRENT_DATETIME` once from the `<current_datetime>` value in your system context. Sanity-check that it is a real ISO-like timestamp, not placeholder text, with a plausible year and timezone (`Z` or an offset). If the system value is missing or implausible, run a local date command and use that result instead (`date +"%Y-%m-%dT%H:%M:%S%z"` on macOS/Linux, or `Get-Date -Format o` in PowerShell). Pass the team root and the resolved literal current datetime into every spawn prompt as `TEAM_ROOT` and `CURRENT_DATETIME` respectively. Never pass placeholder text for `CURRENT_DATETIME`. Pass the current user's name into every agent spawn prompt and Scribe log so the team always knows who requested the work. Check `.squad/identity/now.md` if it exists — it tells you what the team was last focused on. Update it if the focus has shifted.
+**On every session start:** Run `git config user.name` to identify the current user, and **resolve the team root** (see Worktree Awareness). Store the team root — all `.squad/` paths must be resolved relative to it. Resolve `CURRENT_DATETIME` once from the `<current_datetime>` value in your system context. Sanity-check that it is a real ISO-like timestamp, not placeholder text, with a plausible year and timezone (`Z` or an offset). If the system value is missing or implausible, run a local date command and use that result instead (`date +"%Y-%m-%dT%H:%M:%S%z"` on macOS/Linux, or `Get-Date -Format o` in PowerShell). Pass the team root and the resolved literal current datetime into every spawn prompt as `TEAM_ROOT` and `CURRENT_DATETIME` respectively. Never pass placeholder text for `CURRENT_DATETIME`. Pass the current user's name into every agent spawn prompt so the team always knows who requested the work. Check `.squad/identity/now.md` if it exists — it tells you what the team was last focused on. Update it if the focus has shifted.
 
 **Resolve state backend:** Read `.squad/config.json` (at the resolved TEAM_ROOT) and check the `stateBackend` field. Valid values: `"local"` (default), `"orphan"`, `"two-layer"`. Legacy alias: `"worktree"` maps to `"local"`. Deprecated: `"git-notes"` maps to `"two-layer"` with a deprecation warning. Store as `STATE_BACKEND` and pass it into every spawn prompt. This determines how agents read and write mutable state (history, decisions, logs). Static config (charters, team.md, routing.md) always lives on disk regardless of backend. The `"two-layer"` option combines git-notes (commit-scoped annotations) with orphan branch (permanent state) — see the blog post for the full architecture.
 
@@ -201,7 +201,6 @@ For each squad member with assigned issues, note them in the session context. Wh
   ```
   🔧 Runtime Engineer — error handling in index.js
   🧪 Quality Engineer — writing test cases
-  📋 Scribe — logging session
   ```
 
 The acknowledgment goes in the same response as the `task` tool calls — text first, then tool calls. Keep it to 1-2 sentences plus the table. Don't narrate the plan; just show who's working on what.
@@ -237,7 +236,7 @@ When spawning agents, include the role emoji in the `description` parameter to m
 - `name: "lead"`, `description: "🏗️ Lead: Reviewing architecture proposal"`
 - `name: "runtime-engineer"`, `description: "🔧 Runtime Engineer: Refactoring auth module"`
 - `name: "quality-engineer"`, `description: "🧪 Quality Engineer: Writing test cases"`
-- `name: "scribe"`, `description: "📋 Scribe: Log session & merge decisions"`
+- `name: "scribe"`, `description: "📋 Scribe: Merge durable decisions"`
 
 The `name` parameter generates the human-readable agent ID shown in the tasks panel — it MUST be the agent's lowercase cast name (e.g., `"runtime-engineer"`, `"quality-engineer"`). Without it, the platform shows generic slugs like "general-purpose-task" instead of the cast name. The emoji in `description` makes task spawn notifications visually consistent with the launch table shown to users.
 
@@ -634,7 +633,7 @@ when needed, and present compact outcomes. Spawn Scribe only when durable decisi
 merging. Keep the same accountable owner for follow-up work unless a new independently deliverable
 outcome requires rerouting.
 
-**On-demand reference:** Read `.squad/templates/after-agent-reference.md` for the full silent-success rules, Scribe spawn template, and follow-up sequence.
+**On-demand reference:** Read `.squad/templates/after-agent-reference.md` for the full silent-success rules and follow-up sequence. Its Scribe spawn prompt is identical to the Scribe Spawn Template above; Scribe's duties come only from its charter.
 
 ### Ceremonies
 
@@ -646,7 +645,7 @@ Ceremonies are structured team meetings where agents align before or after work.
 1. Before spawning a work batch, check `.squad/ceremonies.md` for auto-triggered `before` ceremonies matching the current task condition.
 2. After a batch completes, check for `after` ceremonies. Manual ceremonies run only when the user asks.
 3. Spawn the facilitator (sync) using the template in the reference file. Facilitator spawns participants as sub-tasks.
-4. For `before`: include ceremony summary in work batch spawn prompts. Spawn Scribe (background) to record.
+4. For `before`: include ceremony summary in work batch spawn prompts. The facilitator records ceremony decisions with `squad_decide`; Scribe merges them later like any other inbox entry.
 5. **Ceremony cooldown:** Skip auto-triggered checks for the immediately following step.
 6. Show: `📋 {CeremonyName} completed — facilitated by {Lead}. Decisions: {count} | Action items: {count}.`
 

.squad-templates/README.md

@@ -29,7 +29,7 @@ of these — they are NOT loaded on every turn.
 | `mcp-config.md` | Coordinator | MCP server integration details |
 | `model-selection-reference.md` | Coordinator | Per-agent model and reasoning-effort selection |
 | `multi-agent-format.md` | Coordinator | Assembling multi-agent artifact output |
-| `orchestration-log.md` | Scribe | Writing per-agent orchestration log entries |
+| `orchestration-log.md` | Legacy (no default writer; not Scribe) | Format of per-agent orchestration log entries |
 | `plugin-marketplace.md` | Coordinator | Plugin marketplace discovery and install flow |
 | `prd-intake.md` | Coordinator | PRD Mode — ingesting a spec for decomposition |
 | `ralph-reference.md` | Coordinator | Ralph work-monitor lifecycle and board format |

.squad-templates/after-agent-reference.md

@@ -7,9 +7,9 @@
      (2) "Server Error Retry Loop" — context overflow after fan-out. Mitigated by lean
      post-work turn + Scribe delegation + compact result presentation. -->
 
-**⚡ Keep the post-work turn LEAN.** Coordinator's job: (1) present compact results, (2) spawn Scribe. That's ALL. No orchestration logs, no decision consolidation, no heavy file I/O.
+**⚡ Keep the post-work turn LEAN.** Coordinator's job: (1) present compact results, (2) spawn Scribe only when accepted durable decisions need merging. That's ALL. No session or orchestration logs, no decision consolidation, no heavy file I/O.
 
-**⚡ Context budget rule:** After collecting results from 3+ agents, use compact format (agent + 1-line outcome). Full details go in orchestration log via Scribe.
+**⚡ Context budget rule:** After collecting results from 3+ agents, use compact format (agent + 1-line outcome). Do not paste full agent output. Durable outcomes belong in decisions (`squad_decide`); each agent appends its own learnings to its own `history.md`.
 
 After each batch of agent work:
 
@@ -22,63 +22,34 @@ After each batch of agent work:
 
 3. **Show compact results:** `{emoji} {Name} — {1-line summary of what they did}`
 
-4. **Spawn Scribe** (background, never wait). Only if agents ran or inbox has files:
+4. **Spawn Scribe** (background, never wait) only when `decisions/inbox` holds accepted durable decisions to merge. Scribe's duties come only from its charter (`.squad/agents/scribe/charter.md`). The prompt below must stay identical to the **Scribe Spawn Template** in `squad.agent.md`:
 
 ```
 agent_type: "general-purpose"
 model: "claude-haiku-4.5"
 mode: "background"
 name: "scribe"
-description: "📋 Scribe: Log session & merge decisions"
+description: "📋 Scribe: Merge durable decisions"
 prompt: |
   You are the Scribe. Read .squad/agents/scribe/charter.md.
   TEAM ROOT: {team_root}
   CURRENT_DATETIME: <resolved CURRENT_DATETIME literal>
   STATE_BACKEND: {state_backend}
 
-  SPAWN MANIFEST: {spawn_manifest}
-
   Tasks (in order):
-  0. PRE-CHECK: Run `squad_state_health` when available. If state tools are unavailable,
-     stop without mutating files or git state.
-  0b. PRE-CHECK: Read `decisions.md` and list `decisions/inbox` with state tools.
-     Record measurements.
-  1. DECISIONS ARCHIVE [HARD GATE]: If decisions.md >= 20480 bytes, archive entries older than 30 days NOW. If >= 51200 bytes, archive entries older than 7 days. Do not skip this step. Follow the ARCHIVAL SAFETY RULES below — they are not optional.
-  2. DECISION INBOX: Use `squad_state_list` and `squad_state_read` on `decisions/inbox`,
-     merge entries into `decisions.md` with `squad_state_write`, delete processed inbox
-     entries with `squad_state_delete`, and deduplicate. Before splicing an inbox body
-     beneath an `###` entry, DEMOTE its headings so its shallowest heading lands at
-     `####` (`##` -> `####`). Preserve relative structure. Never emit an `##` under an `###`.
-  3. ORCHESTRATION LOG: Write `orchestration-log/{timestamp}-{agent}.md` with `squad_state_write` per agent. Use ISO 8601 UTC timestamp. Replace `:` with `-` in `{timestamp}` so filenames are valid on all platforms (e.g. `2026-06-02T21-15-30Z`).
-  4. SESSION LOG: Write `log/{timestamp}-{topic}.md` with `squad_state_write`. Brief. Use ISO 8601 UTC timestamp. Replace `:` with `-` in `{timestamp}` so filenames are valid on all platforms.
-  5. CROSS-AGENT: Append team updates to affected agents' `agents/{agent}/history.md` with `squad_state_append`.
-  6. HISTORY SUMMARIZATION [HARD GATE]: If any history.md >= 15360 bytes (15KB), summarize now. The ARCHIVAL SAFETY RULES apply here too — summarization moves content out of a file exactly like decision archival does.
-  7. HEALTH REPORT: Report ENTRY COUNTS, never file sizes: `N removed from source / N added to destination` for every archival, plus inbox count processed and history files summarized. Write with `squad_state_write` or `squad_state_append`.
-
-  ARCHIVAL SAFETY RULES (apply to every operation that moves content out of a file):
-  A. DESTINATION MUST BE TRACKED. Before writing, run `git ls-files --error-unmatch <destination>`.
-     Exit 0 -> proceed. Non-zero -> redirect to an existing tracked archive file, or ABORT with a
-     clear error. `.squad/` is git-excluded in many checkouts: already-tracked files still commit,
-     but NEW files silently never do. Moving content into an untracked destination is a DELETION,
-     not an archive. Never create a new timestamped archive file and assume it will commit.
-  B. APPEND FIRST, VERIFY, THEN DELETE. Append to the destination. Re-read the destination and
-     confirm every moved heading is literally present AND the entry count grew by exactly the
-     number moved. Only then remove from the source. If the append cannot be verified, DO NOT
-     trim — leave the source intact and report the failure. Losing history is far worse than
-     leaving a file over its size gate.
-  C. COUNT ENTRIES, NOT BYTES. File size is not a valid integrity signal: a merge and an archive
-     in the same pass move size in opposite directions, so a size delta proves nothing.
-  D. NEVER REPORT A GATE OUTCOME YOU DID NOT MEASURE. "No archival required" must come from an
-     actual measurement. A gate that reports without measuring is worse than no gate.
-  E. If a state tool cannot perform these checks, STOP and report rather than proceeding with an
-     unverified move.
-
-  Runtime state tools own persistence. Never switch branches, push note refs, reset
-  `.squad/`, or commit mutable squad state from this prompt.
-
-  Never speak to user. ⚠️ End with plain text summary after all tool calls.
+  0. PRE-CHECK: Run `squad_state_health` when available. If state tools are unavailable, stop without mutating files or git state.
+  0b. PRE-CHECK: Read `decisions.md` and list `decisions/inbox` with state tools. Record measurements.
+  1. DECISION INBOX: Use `squad_state_list` and `squad_state_read` on `decisions/inbox`, merge accepted durable decisions into `decisions.md` with `squad_state_write`, delete processed inbox entries with `squad_state_delete`, and deduplicate. Before splicing an inbox body beneath an `###` entry, DEMOTE its headings so its shallowest heading lands at `####` (`##` -> `####`). Preserve relative structure. Never emit an `##` under an `###`.
+  2. VERIFY: Re-read `decisions.md` and confirm every merged entry is present before deleting its inbox source.
+  3. GIT COMMIT: Do not commit mutable squad state. If non-state repo files changed, report them for coordinator handling.
+
+  Runtime state tools own persistence. Never switch branches, push note refs, reset `.squad/`, or commit mutable squad state from this prompt.
+
+  Never speak to user. End with plain text summary after all tool calls.
 ```
 
+Scribe does not write session logs, orchestration logs or other agents' `history.md`, and it does not archive. Size hygiene (archiving old decisions, compressing large histories, pruning old logs) is the `squad nap` CLI command, not a Scribe task.
+
 5. **Immediately assess:** Does anything trigger follow-up work? Launch it NOW.
 
 6. **Ralph check:** If Ralph is active (see Ralph — Work Monitor), after chaining any follow-up work, IMMEDIATELY run Ralph's work-check cycle (Step 1). Do NOT stop. Do NOT wait for user input. Ralph keeps the pipeline moving until the board is clear.

.squad-templates/ceremony-reference.md

@@ -56,6 +56,7 @@ RULES:
 - Follow the agenda in order.
 - For each agenda item, spawn relevant participants as sub-tasks to gather their input.
 - Synthesize participant input into clear decisions and action items.
+- Record each decision with `squad_decide` (one call per decision) so Scribe can merge it.
 - Keep to the time budget: {focused|extended}.
 - Output a structured summary at the end.
 
@@ -73,7 +74,7 @@ TASK CONTEXT:
    - `all-relevant` → agents routed to the current task
    - `all-involved` → agents that participated in the completed batch
    - Named agents → spawn only those specific agents
-6. **Scribe integration:** Spawn Scribe (background) at ceremony start to record decisions and action items.
+6. **Scribe integration:** The facilitator records ceremony decisions with `squad_decide`. Scribe merges them afterwards like any other inbox entry; do not spawn Scribe at ceremony start.
 7. **Output format:**
    ```
    📋 {CeremonyName} completed — facilitated by {Facilitator}.

.squad-templates/model-selection-reference.md

@@ -70,7 +70,7 @@ Quality-sensitive work that is not code (architecture, research, verification, r
 | Copilot SDK Expert | Standard | Technical analysis that often touches code | Deep research → premium |
 | Designer / Visual | Premium | Vision-capable model required | — (never downgrade — vision is non-negotiable) |
 | DevRel / Writer | Standard | Language-heavy work benefits from a stronger model | Economy profile → fast |
-| Scribe / Logger | Fast | Mechanical file ops | — (never bump Scribe) |
+| Scribe | Fast | Mechanical decision merging | — (never bump Scribe) |
 | Git / Release | Fast | Mechanical ops — changelogs, tags, version bumps | — (never bump mechanical ops) |
 
 **Task complexity adjustments** (apply at most ONE — no cascading):
@@ -119,7 +119,7 @@ Every spawn acknowledgment names the resolved model, its source and a short rati
 
 🔧 Runtime Engineer ({model} · session) — refactoring auth module — session model inherited by this spawn
 🎨 Experience Engineer ({model} · task-auto) — designing color system — visual task needs vision → premium tier
-📋 Scribe ({model} · task-auto) — logging session — mechanical task → fast tier
+📋 Scribe ({model} · task-auto) — merging decisions — mechanical task → fast tier
 ⚡ Lead ({model} · config) — reviewing proposal — agentModelOverrides.lead in .squad/config.json
 📝 Docs Engineer ({model} · fallback) — updating docs — charter model unavailable; next in fast chain
 ```

.squad-templates/routing.md

@@ -27,7 +27,7 @@ here only when their agent names also exist in the casting registry.
 ## Rules
 
 1. **Eager by default** — spawn all agents who could usefully start work, including anticipatory downstream work.
-2. **Scribe always runs** after substantial work, always as `mode: "background"`. Never blocks.
+2. **Scribe runs only when accepted durable decisions need merging**, always as `mode: "background"`. Never blocks.
 3. **Quick facts → coordinator answers directly.** Don't spawn an agent for "what port does the server run on?"
 4. **When two agents could handle it**, pick the one whose domain is the primary concern.
 5. **"Team, ..." → fan-out.** Spawn all relevant agents in parallel as `mode: "background"`.

.squad-templates/scribe-charter.md

@@ -23,7 +23,7 @@ records, communications records, hooks, E2E records, or onboarding output.
 
 **State backend awareness:** Use runtime state tools for non-local backends, including `squad_state_read`, `squad_state_write`, `squad_state_append`, `squad_state_create_if_absent`, `squad_state_delete`, `squad_state_list`, `squad_state_health`, and `squad_decide`. Never switch state branches, push note refs, reset `.squad/`, or commit mutable state manually. If required state tools are unavailable, stop without mutating state and report the failure to the coordinator.
 
-**Exclusive canonical artifacts:** When exactly one canonical artifact must exist — a retrospective, a session log, a claim marker — create it with `squad_state_create_if_absent`, never `squad_state_write`. It creates the key atomically only when absent, so exactly one Scribe wins and existing content is never overwritten. Handle its two failure shapes explicitly:
+**Exclusive canonical artifacts:** When exactly one canonical artifact must exist, such as a claim marker, create it with `squad_state_create_if_absent`, never `squad_state_write`. It creates the key atomically only when absent, so exactly one Scribe wins and existing content is never overwritten. Handle its two failure shapes explicitly:
 
 - `error: "conflict"` — another Scribe already created the canonical artifact. Do **not** retry as a create and do **not** overwrite. Read the winner's content with `squad_state_read` and append to it if you have something to add.
 - `error: "uncertainty"` — the outcome is unknown. Do **not** assume success and do **not** write over the key. Stop and report the uncertainty in your final summary.