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 378431a..939103a 100644 --- a/.vault/scripts/lib-manage.sh +++ b/.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 diff --git a/AGENTS.md b/AGENTS.md index 225431d..7b4d000 100644 --- a/AGENTS.md +++ b/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 diff --git a/CHANGELOG.md b/CHANGELOG.md index 412f9e9..a063507 100644 --- a/CHANGELOG.md +++ b/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//` 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 diff --git a/CLAUDE.md b/CLAUDE.md index b47ba9f..0aec983 100644 --- a/CLAUDE.md +++ b/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 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 cb5f01a..520e968 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