docs(rules): add SR-016 one-writer convention and memory/agents/ scratch space

.vault/rules/soft-rules.md

@@ -212,3 +212,21 @@ prefer appending to an existing relevant page over creating a new page.
 - Use lowercase, hyphenated values: `domain/data-engineering` not `domain/DataEngineering`
 - Add new tags to `.vault/rules/tags.md` before using them
 - Prefix custom tags with `custom/` if they are organization-specific and unlikely to be useful in the boilerplate: `custom/acme-internal`
+
+---
+
+## SR-016: One Writer per Branch
+
+**Default**: Within a single branch, `wiki/` has exactly **one writing agent**. Other agents working on the same branch write to their namespaced
+scratch space in `memory/agents/<agent-id>/` instead. Scratch notes are promoted into `wiki/` by the single writer.
+
+**Guidance**:
+
+- Name scratch directories after the stable agent ID used in branch names: `memory/agents/claude-01/`
+- Scratch notes are free-form working files; they become subject to the full wiki conventions only when promoted
+- The single writer reviews, reconciles, and files scratch content into `wiki/`, updating `wiki/index.md` and `wiki/log.md` as usual
+
+**Rationale**: One writer per branch prevents merge conflicts and semantic corruption in `wiki/` without requiring file-level locks.
+Branch-per-session remains the primary isolation mechanism; this rule covers the case where multiple agents share a branch.
+
+**When to override**: Single-agent sessions — the rule is trivially satisfied. This is a **coordination protocol, not an enforced policy**: no hook or lint check verifies it.

.vault/scripts/lib-manage.sh

@@ -212,6 +212,16 @@ cmd_doctor() {
         fi
     done
 
+    # Optional directories — present is healthy, absent is not an error.
+    # memory/agents/ holds per-agent scratch space (SR-016); its
+    # per-agent subdirectories are free-form and never flagged.
+    local optional_dirs=("memory/agents")
+    for dir in "${optional_dirs[@]}"; do
+        if [[ -d "${VAULT_ROOT}/${dir}" ]]; then
+            ok "${dir}/ (optional)"
+        fi
+    done
+
     subheader "Required Files"
     local required_files=("CLAUDE.md" "AGENTS.md" "wiki/index.md" "wiki/log.md" "memory/status.md" ".vault/rules/hard-rules.md" ".vault/rules/soft-rules.md" ".vault/rules/tags.md" ".vault/schemas/frontmatter.md")
     for file in "${required_files[@]}"; do

AGENTS.md

@@ -129,6 +129,12 @@ confidence: high | medium | low | unverified
 - PRs require lint pass before merge
 - Main branch is protected
 
+## Multi-Agent Scratch Space
+
+- One writing agent per branch for `wiki/` (SR-016); other agents on the same branch write to `memory/agents/{{agent-id}}/`
+- The single writer promotes scratch notes into `wiki/`
+- Coordination protocol only — not enforced by hooks or lint
+
 ## Security
 
 ### Content Trust Levels

CHANGELOG.md

@@ -48,6 +48,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   missing or exceeds 200 lines. Context loading order in `CLAUDE.md`,
   `AGENTS.md`, and `CODEX.md` updated to include it. Covered by
   `.vault/scripts/tests/test-memory-refresh.sh` (#11).
+- SR-016 "One Writer per Branch": within a single branch, `wiki/` has
+  exactly one writing agent; other agents on the same branch write to
+  their namespaced scratch space under `memory/agents/<agent-id>/` and
+  the single writer promotes scratch notes into `wiki/`. Coordination
+  protocol, not enforced policy. Documented in `docs/git-workflow.md`,
+  `CLAUDE.md`, and `AGENTS.md`; `doctor` now lists the optional
+  `memory/agents/` directory (#13).
 
 ### Changed
 

CLAUDE.md

@@ -207,6 +207,13 @@ See `.vault/rules/tags.md` for the full taxonomy: 19 prefix categories, 230 appr
 - PRs require lint pass before merge
 - Main branch is protected
 
+### Multi-Agent Scratch Space
+
+- Within a single branch, `wiki/` has exactly one writing agent (SR-016)
+- Other agents on the same branch write to their namespaced scratch space: `memory/agents/{{agent-id}}/`
+- Scratch notes are promoted into `wiki/` by the single writer
+- Coordination protocol only — not enforced by hooks or lint
+
 ## Security
 
 ### Content Trust Levels

CONTRIBUTING.md

@@ -66,7 +66,7 @@ fix(hooks): correct frontmatter date parsing for BSD date
 docs(vault): add batch ingestion example to ingestion guide
 chore(ci): update markdownlint-cli2 action to v19
 refactor(scripts): extract frontmatter parser into shared function
-feat(rules): add SR-016 for minimum entity page completeness
+feat(rules): add SR-0XX for minimum entity page completeness
 docs(templates): add report template with executive summary section
 ```
 

docs/configuration.md

@@ -55,6 +55,7 @@ Edit `.vault/rules/soft-rules.md` to customize agent behavior. Each rule has a d
 | SR-013 | Entity page structure | Customize sections |
 | SR-014 | Comparison page structure | Customize sections |
 | SR-015 | Custom tags use `custom/` prefix | Define your prefix convention |
+| SR-016 | One `wiki/` writer per branch | Adapt scratch-space naming under `memory/agents/` |
 
 Agents read `soft-rules.md` during context loading. Changes take effect on the next agent session.
 

docs/git-workflow.md

@@ -125,6 +125,16 @@ Multiple agents can work on the vault simultaneously because each operates on it
 - Keep operations atomic -- small, focused changes merge more cleanly
 - Stagger large ingestions rather than running them in parallel
 
+### One writer per branch (SR-016)
+
+Branch-per-session remains the primary isolation mechanism. When multiple agents do share a single branch, apply the one-writer convention from SR-016 in `.vault/rules/soft-rules.md`:
+
+- Exactly **one agent** writes to `wiki/` on that branch
+- Every other agent writes to its own scratch space: `memory/agents/<agent-id>/` (e.g., `memory/agents/codex-02/`)
+- Scratch notes are promoted into `wiki/` by the single writer, which reconciles them and updates `wiki/index.md` and `wiki/log.md`
+
+This is a coordination protocol, not an enforced policy -- no hook or lint check verifies it.
+
 ## Resolving Conflicts
 
 ### wiki/index.md (most common)

docs/rules-customization.md

@@ -28,7 +28,7 @@ system works.
 
 ## Creating a Soft Rule
 
-1. Choose the next ID (SR-016, SR-017, etc.)
+1. Choose the next unused ID (one greater than the highest SR number in `.vault/rules/soft-rules.md`)
 2. Add to `.vault/rules/soft-rules.md`:
 
 ```markdown

docs/rules-guide.md

@@ -12,7 +12,7 @@ enforced by the pre-commit git hook. A commit that violates any hard
 rule is rejected. Hard rules protect vault integrity — they prevent
 data loss, corruption, and security breaches.
 
-**Soft rules** (SR-001 through SR-015) are configurable guidelines
+**Soft rules** (SR-001 through SR-016) are configurable guidelines
 checked during lint operations. Violations generate warnings, not
 rejections. Soft rules encode best practices that vary by organization.