From 11abbd1032aeec5c97d7c3cab6ee8039cb36fe66 Mon Sep 17 00:00:00 2001 From: galimba Date: Tue, 7 Jul 2026 16:56:29 +0200 Subject: [PATCH] docs(rules): add SR-016 one-writer convention and memory/agents/ scratch space MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit New soft rule SR-016 "One Writer per Branch": within a single branch, wiki/ has exactly one writing agent; other agents write to their namespaced scratch space memory/agents// and promote notes through the single writer. Coordination protocol, not enforced policy. Creates memory/agents/ (gitkeep), documents the convention in docs/git-workflow.md and the agent-config files, teaches doctor to recognize memory/agents/ subdirectories, and bumps soft-rule count references to 16. Filed as SR-016 (the issue proposed SR-017 — off-by-one; SR-015 was the previous maximum). Closes #13 Co-Authored-By: Claude Fable 5 --- .vault/rules/soft-rules.md | 18 ++++++++++++++++++ .vault/scripts/lib-manage.sh | 10 ++++++++++ AGENTS.md | 6 ++++++ CHANGELOG.md | 10 ++++++++++ CLAUDE.md | 7 +++++++ CONTRIBUTING.md | 2 +- docs/configuration.md | 1 + docs/git-workflow.md | 10 ++++++++++ docs/rules-customization.md | 2 +- docs/rules-guide.md | 2 +- memory/agents/.gitkeep | 0 11 files changed, 65 insertions(+), 3 deletions(-) create mode 100644 memory/agents/.gitkeep diff --git a/.vault/rules/soft-rules.md b/.vault/rules/soft-rules.md index 79fd4ab..17364b9 100644 --- a/.vault/rules/soft-rules.md +++ b/.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//` 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. diff --git a/.vault/scripts/lib-manage.sh b/.vault/scripts/lib-manage.sh index 46d1aaf..d0986ea 100644 --- a/.vault/scripts/lib-manage.sh +++ b/.vault/scripts/lib-manage.sh @@ -210,6 +210,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 diff --git a/AGENTS.md b/AGENTS.md index e50eb24..f7ef64c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -128,6 +128,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 diff --git a/CHANGELOG.md b/CHANGELOG.md index 635b357..322e34c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Added + +- 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//` 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). + ## [0.5.0] - 2026-07-07 ### Added diff --git a/CLAUDE.md b/CLAUDE.md index 46775b4..f279ce8 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -205,6 +205,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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 672815a..efe8a66 100644 --- a/CONTRIBUTING.md +++ b/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 ``` diff --git a/docs/configuration.md b/docs/configuration.md index 87c4995..cae6a74 100644 --- a/docs/configuration.md +++ b/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. diff --git a/docs/git-workflow.md b/docs/git-workflow.md index e3f1e75..9358b6c 100644 --- a/docs/git-workflow.md +++ b/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//` (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) diff --git a/docs/rules-customization.md b/docs/rules-customization.md index ccd1c7c..0bd840c 100644 --- a/docs/rules-customization.md +++ b/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 diff --git a/docs/rules-guide.md b/docs/rules-guide.md index 164431d..8da5a9a 100644 --- a/docs/rules-guide.md +++ b/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. diff --git a/memory/agents/.gitkeep b/memory/agents/.gitkeep new file mode 100644 index 0000000..e69de29