galimba · galimba · Jul 8, 2026 · Jul 7, 2026 · Jul 7, 2026 · Jul 7, 2026
diff --git a/.vault/rules/hard-rules.md b/.vault/rules/hard-rules.md
@@ -2,9 +2,12 @@
 
 > These rules are enforced by hooks and pre-commit scripts. Violations block commits. These rules exist to maintain vault integrity, agent reliability, and data safety. They are not configurable.
 
+The key words **MUST**, **MUST NOT**, **SHOULD**, **SHOULD NOT**, and **MAY** in this document are to
+be interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119).
+
 ## HR-001: Raw Directory Immutability
 
-**Rule**: No agent or automated process may create, modify, rename, or delete files in `raw/`. Only humans add files to `raw/` (manually or via Obsidian Web Clipper).
+**Rule**: Agents and automated processes **MUST NOT** create, modify, rename, or delete files in `raw/`. Only humans add files to `raw/` (manually or via Obsidian Web Clipper).
 
 **Rationale**: `raw/` is the provenance layer. If sources can be modified after ingestion, the wiki loses its grounding truth. Every wiki claim must trace back to an unmodified source.
 
@@ -17,7 +20,7 @@ approval for PRs touching `raw/`.
 
 ## HR-002: Mandatory Frontmatter
 
-**Rule**: Every `.md` file in `wiki/` MUST begin with valid YAML frontmatter containing at minimum: `title`, `type`, `created`, `updated`, `status`, `tags`.
+**Rule**: Every `.md` file in `wiki/` **MUST** begin with valid YAML frontmatter containing at minimum: `title`, `type`, `created`, `updated`, `status`, `tags`.
 
 **Rationale**: Frontmatter is how agents discover, filter, and reason about vault contents.
 Without it, pages become invisible to programmatic access.
@@ -29,7 +32,7 @@ Dataview queries, index generation, and lint operations all depend on structured
 
 ## HR-003: Mandatory Tags
 
-**Rule**: Every file in `wiki/` MUST include at least one tag from the approved taxonomy (`.vault/rules/tags.md`). Tags MUST use the flat prefix notation: `prefix/value`.
+**Rule**: Every file in `wiki/` **MUST** include at least one tag from the approved taxonomy (`.vault/rules/tags.md`). Tags **MUST** use the flat prefix notation: `prefix/value`.
 
 **Rationale**: Tags are the primary discovery mechanism for agents.
 A page without tags is a page that cannot be found by category, domain, or type.
@@ -42,7 +45,7 @@ Flat prefixes ensure consistent machine parsing without ambiguity.
 ## HR-004: Markdown Length Limit
 
 **Rule**: Markdown files in `wiki/` or `memory/` should stay under **200
-lines** (soft warning). Files exceeding **400 lines** are blocked (hard
+lines** (soft warning) and **MUST NOT** exceed **400 lines** (hard
 limit). If content requires more space, split into linked sub-pages with
 a parent page that serves as an index.
 
@@ -69,8 +72,8 @@ keeps its section headings and links to them.
 ## HR-005: Code File Length Limit
 
 **Rule**: Standalone code files (`.sh`, `.py`, `.js`, `.ts`, etc.) in
-`.vault/` should stay under **400 lines** (soft warning). Files exceeding
-**600 lines** are blocked (hard limit). If a file exceeds the limit, split
+`.vault/` should stay under **400 lines** (soft warning) and **MUST NOT**
+exceed **600 lines** (hard limit). If a file exceeds the limit, split
 it into modular files with clear responsibilities and a single entry point
 that sources them.
 
@@ -92,7 +95,7 @@ ability to stay under the limit. Configuration files (`.json`, `.yaml`,
 
 ## HR-006: Unique Page Titles
 
-**Rule**: No two files in `wiki/` may share the same `title` frontmatter value. Titles are the primary human-readable identifier and the basis for `[[wikilink]]` resolution.
+**Rule**: Two files in `wiki/` **MUST NOT** share the same `title` frontmatter value. Titles are the primary human-readable identifier and the basis for `[[wikilink]]` resolution.
 
 **Rationale**: Duplicate titles cause ambiguous wikilinks.
 When an agent writes `[[API Design Principles]]` and two pages share that title,
@@ -104,9 +107,9 @@ the link target is undefined. Uniqueness eliminates this class of error.
 
 ## HR-007: Updated Field Accuracy
 
-**Rule**: The `updated` field in frontmatter MUST reflect the actual date
+**Rule**: The `updated` field in frontmatter **MUST** reflect the actual date
 of the last meaningful content change.
-Agents MUST update this field whenever they modify page content
+Agents **MUST** update this field whenever they modify page content
 (not for metadata-only changes).
 
 **Rationale**: The `updated` field drives staleness detection in lint operations. An inaccurate date means stale content goes undetected, degrading vault quality over time.
@@ -117,12 +120,12 @@ Agents MUST update this field whenever they modify page content
 
 ## HR-008: Index Registration
 
-**Rule**: Every file in `wiki/` MUST be registered in the index — either in
-the root `wiki/index.md` OR in any `wiki/index-*.md` sub-index (the split-index
-layout produced by `vault-tools.sh index-split`). The entry must include the
-file path and a one-line summary. The index files themselves are structural
-and exempt: `wiki/index.md`, every `wiki/index-*.md` sub-index, and
-`wiki/log.md`.
+**Rule**: Every file in `wiki/` **MUST** be registered in the index — either
+in the root `wiki/index.md` OR in any `wiki/index-*.md` sub-index (the
+split-index layout produced by `vault-tools.sh index-split`). The entry
+**MUST** include the file path and a one-line summary. The index files
+themselves are structural and exempt: `wiki/index.md`, every
+`wiki/index-*.md` sub-index, and `wiki/log.md`.
 
 **Rationale**: The index is the primary retrieval mechanism.
 Agents read it first to locate relevant pages.
@@ -140,7 +143,7 @@ frontmatter `type`.
 
 ## HR-009: Flat Tag Notation
 
-**Rule**: Tags MUST use exactly one level of prefixing: `prefix/value`. No deeper nesting (`prefix/sub/value`), no bare tags without prefix (`#concept`), no spaces in tags.
+**Rule**: Tags **MUST** use exactly one level of prefixing: `prefix/value`. Tags **MUST NOT** use deeper nesting (`prefix/sub/value`), appear bare without a prefix (`#concept`), or contain spaces.
 
 **Rationale**: Flat prefixes balance expressiveness with parseability.
 A single `grep` or `awk` command can extract all tags of a given prefix.
@@ -155,8 +158,8 @@ Bare tags without prefixes are ambiguous
 ## HR-010: Binary File Quarantine
 
 **Rule**: Binary files (images, PDFs, spreadsheets, archives, executables)
-MUST be stored in `raw/` only.
-The `wiki/` and `memory/` directories may contain only `.md` files
+**MUST** be stored in `raw/` only.
+The `wiki/` and `memory/` directories **MUST** contain only `.md` files
 and `.json` configuration files.
 
 **Rationale**: Binary files cannot be diffed by git, cannot be read by agents,
@@ -172,7 +175,7 @@ rather than embedding them.
 
 ## HR-011: Vault Configuration Protection
 
-**Rule**: No agent may modify files in `.vault/rules/`, `.vault/hooks/`,
+**Rule**: Agents **MUST NOT** modify files in `.vault/rules/`, `.vault/hooks/`,
 or `.vault/scripts/`. These directories contain the vault's governance
 and enforcement mechanisms. Changes require human-authored PRs.
 
@@ -188,7 +191,7 @@ in `.vault/rules/`, `.vault/hooks/`, or `.vault/scripts/`.
 
 ## HR-012: Agent Configuration Protection
 
-**Rule**: No agent may modify `CLAUDE.md`, `AGENTS.md`, or `CODEX.md`.
+**Rule**: Agents **MUST NOT** modify `CLAUDE.md`, `AGENTS.md`, or `CODEX.md`.
 These files define agent behavior constraints. Changes require
 human-authored PRs.
 
@@ -204,7 +207,7 @@ critical protection after raw/ immutability.
 
 ## HR-013: CI and Template Protection
 
-**Rule**: No agent may modify files in `.github/` or `templates/`.
+**Rule**: Agents **MUST NOT** modify files in `.github/` or `templates/`.
 Workflow files control CI enforcement. Template files shape all future
 wiki pages.
 
@@ -220,7 +223,7 @@ in `.github/` or `templates/`.
 
 ## HR-014: No File Deletion
 
-**Rule**: Agents must not delete files from `wiki/` or `memory/`.
+**Rule**: Agents **MUST NOT** delete files from `wiki/` or `memory/`.
 To remove content from the active vault, set `status: archived` in
 the file's frontmatter. The file remains in the working tree and
 git history but is excluded from active queries, lint reports, and
@@ -252,8 +255,8 @@ message.
 ## HR-015: Append-Only Logs
 
 **Rule**: `wiki/log.md` and files under `memory/logs/` are append-only.
-Commits that delete or modify existing lines in these files are rejected.
-Only pure additions are allowed.
+Existing lines in these files **MUST NOT** be deleted or modified;
+commits that do so are rejected. Only pure additions are allowed.
 
 **Rationale**: The operations log is the vault's audit trail. If agents
 can rewrite log history, there is no reliable record of what happened.

diff --git a/.vault/rules/soft-rules.md b/.vault/rules/soft-rules.md
@@ -2,12 +2,15 @@
 
 > These rules are recommendations, not hard enforcement.
 > Customize them for your organization.
-> Agents should follow these unless instructed otherwise.
+> Agents **SHOULD** follow these unless instructed otherwise.
 > Violations generate warnings during lint, not commit rejections.
 
+The key words **MUST**, **MUST NOT**, **SHOULD**, **SHOULD NOT**, and **MAY** in this document are to
+be interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119).
+
 ## SR-001: One Source at a Time
 
-**Default**: Ingest one source document per session. Review the generated wiki pages before ingesting the next source.
+**Default**: Agents **SHOULD** ingest one source document per session. Generated wiki pages **SHOULD** be reviewed before ingesting the next source.
 
 **Rationale**: Batch ingestion risks cross-contamination of concepts and reduces human oversight. One-at-a-time builds understanding incrementally.
 
@@ -17,21 +20,21 @@
 
 ## SR-002: Target Page Length
 
-**Default**: Wiki pages should target **80-150 lines** (warn at 200, block at 400). Shorter pages are fine for narrow topics. Pages approaching 200 lines should be proactively split.
+**Default**: Wiki pages **SHOULD** target **80-150 lines** (warn at 200, block at 400). Shorter pages **MAY** be used for narrow topics. Pages approaching 200 lines **SHOULD** be proactively split.
 
 ---
 
 ## SR-003: Minimum Link Density
 
-**Default**: Each wiki page should contain at least **3 wikilinks** to other pages. This ensures the knowledge graph remains connected.
+**Default**: Each wiki page **SHOULD** contain at least **3 wikilinks** to other pages. This ensures the knowledge graph remains connected.
 
 **When to override**: Highly specialized pages with no natural connections. Tag them `lifecycle/orphan-candidate` for future review.
 
 ---
 
 ## SR-004: Source Summary Length
 
-**Default**: Source summaries in `wiki/sources/` should use absolute word
+**Default**: Source summaries in `wiki/sources/` **SHOULD** use absolute word
 count ranges based on source length:
 
 | Source Length | Summary Target |
@@ -40,16 +43,16 @@ count ranges based on source length:
 | 2,000-10,000 words | 500-2,000 words |
 | Over 10,000 words | 2,000-5,000 words |
 
-Never exceed 5,000 words regardless of source length. Summaries should
-capture key claims, data points, and conclusions — not reproduce the
-original. For very short sources (<500 words), the summary may be nearly
-as long as the original if the content is dense.
+Summaries **MUST NOT** exceed 5,000 words regardless of source length.
+Summaries **SHOULD** capture key claims, data points, and conclusions —
+not reproduce the original. For very short sources (<500 words), the
+summary **MAY** be nearly as long as the original if the content is dense.
 
 ---
 
 ## SR-005: Log Entry Format
 
-**Default**: Log entries in `wiki/log.md` follow this format:
+**Default**: Log entries in `wiki/log.md` **SHOULD** follow this format:
 
 ```markdown
 ## [YYYY-MM-DD] operation | Title
@@ -62,7 +65,7 @@ as long as the original if the content is dense.
 
 ## SR-006: Decision Record Format
 
-**Default**: Decision records in `memory/decisions/` use the ADR format:
+**Default**: Decision records in `memory/decisions/` **SHOULD** use the ADR format:
 
 ```markdown
 ---
@@ -93,14 +96,14 @@ What other options were evaluated and why were they rejected?
 
 ## SR-007: Lint Frequency
 
-**Default**: Run a full lint pass at least **once per week**. For active vaults with daily ingestion, run lint daily.
+**Default**: A full lint pass **SHOULD** run at least **once per week**. For active vaults with daily ingestion, lint **SHOULD** run daily.
 
 ---
 
 ## SR-008: Staleness Threshold
 
 **Default**: Pages not updated in **30 days** are flagged as potentially stale during lint.
-This threshold can be adjusted per-domain
+This threshold **MAY** be adjusted per-domain
 (e.g., HR policies may be stable for 90+ days; engineering docs may go stale in 7 days).
 
 **Configuration**: Set thresholds in `.vault/schemas/staleness-config.json`.
@@ -109,7 +112,7 @@ This threshold can be adjusted per-domain
 
 ## SR-009: Confidence Calibration
 
-**Default**: Use the `confidence` frontmatter field as follows:
+**Default**: Agents **SHOULD** use the `confidence` frontmatter field as follows:
 
 | Value | Meaning |
 |-------|---------|
@@ -122,9 +125,9 @@ This threshold can be adjusted per-domain
 
 ## SR-010: Review Gates
 
-**Default**: Pages with `status: draft` should require human review
-before promotion to `status: active`. Agents may create draft pages
-freely but should not auto-promote to active.
+**Default**: Pages with `status: draft` **SHOULD** require human review
+before promotion to `status: active`. Agents **MAY** create draft pages
+freely but **SHOULD NOT** auto-promote to active.
 
 **Enforcement**: This rule is NOT automatically enforced by hooks.
 Enforcement relies on one or more of:
@@ -146,7 +149,7 @@ review.
 
 ## SR-011: Cross-Reference on Ingest
 
-**Default**: When ingesting a new source, the agent should update every
+**Default**: When ingesting a new source, the agent **SHOULD** update every
 existing wiki page that the new source materially affects. A "material
 affect" means the source adds new information, contradicts existing
 claims, or provides updated data relevant to that page.
@@ -164,23 +167,24 @@ claims, or provides updated data relevant to that page.
 
 ## SR-012: Query Filing
 
-**Default**: When an agent answers a query, file the answer back into the
-wiki ONLY if both conditions are met:
+**Default**: When an agent answers a query, the answer **SHOULD** be filed
+back into the wiki ONLY if both conditions are met:
 
 1. **Novelty**: The answer reveals knowledge not already captured in
    existing wiki pages.
 2. **Reusability**: The knowledge is likely to be useful for future
    queries from other agents or humans.
 
 One-off questions, personal preferences, and answers that simply
-recombine existing wiki content should NOT be filed back. When filing,
-prefer appending to an existing relevant page over creating a new page.
+recombine existing wiki content **SHOULD NOT** be filed back. When filing,
+agents **SHOULD** prefer appending to an existing relevant page over
+creating a new page.
 
 ---
 
 ## SR-013: Entity Page Structure
 
-**Default**: Entity pages (people, companies, tools, products) should include:
+**Default**: Entity pages (people, companies, tools, products) **SHOULD** include:
 
 ```
 - Key Facts (structured list)
@@ -194,7 +198,7 @@ prefer appending to an existing relevant page over creating a new page.
 
 ## SR-014: Comparison Page Structure
 
-**Default**: Comparison pages should include:
+**Default**: Comparison pages **SHOULD** include:
 
 ```
 - Summary (which option is recommended and why)
@@ -207,7 +211,7 @@ prefer appending to an existing relevant page over creating a new page.
 
 ## SR-015: Naming Conventions for Custom Tags
 
-**Default**: When adding organization-specific tags beyond the base taxonomy, follow these conventions:
+**Default**: When adding organization-specific tags beyond the base taxonomy, agents **SHOULD** follow these conventions:
 
 - Use lowercase, hyphenated values: `domain/data-engineering` not `domain/DataEngineering`
 - Add new tags to `.vault/rules/tags.md` before using them

diff --git a/AGENTS.md b/AGENTS.md
@@ -76,10 +76,10 @@ Support directories: `.vault/` (config), `templates/` (page templates), `docs/`
 8. **Every `wiki/` file MUST be registered in `wiki/index.md`**
 9. **Tags MUST use flat prefix notation**: `prefix/value`
 10. **Binary files MUST be stored in `raw/`** only
-11. **No agent may modify `.vault/rules/`, `.vault/hooks/`, or `.vault/scripts/`**
-12. **No agent may modify `CLAUDE.md`, `AGENTS.md`, or `CODEX.md`**
-13. **No agent may modify `.github/` or `templates/`**
-14. **Do not delete files from `wiki/` or `memory/`.** Set `status: archived` in frontmatter instead. Use `VAULT_ALLOW_DELETE=1` for cleanup.
+11. **Agents MUST NOT modify `.vault/rules/`, `.vault/hooks/`, or `.vault/scripts/`**
+12. **Agents MUST NOT modify `CLAUDE.md`, `AGENTS.md`, or `CODEX.md`**
+13. **Agents MUST NOT modify `.github/` or `templates/`**
+14. **Agents MUST NOT delete files from `wiki/` or `memory/`.** Set `status: archived` in frontmatter instead. Use `VAULT_ALLOW_DELETE=1` for cleanup.
 15. **Log files (`wiki/log.md`, `memory/logs/`) are append-only** (HR-015). Deletions are rejected. Set `LOG_EDIT_ALLOWED=1` to bypass for legitimate corrections.
 
 Full details: `.vault/rules/hard-rules.md`

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -35,6 +35,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   freshness model. Decay scoring (#8) and lifecycle tier tags (#12) are
   closed as adopter customizations, with build-it-yourself recipes in
   `docs/freshness-customization.md`.
+- `.vault/rules/hard-rules.md` and `.vault/rules/soft-rules.md` now use
+  RFC 2119 keywords consistently — hard rules state requirements with
+  **MUST**/**MUST NOT**, soft rules with **SHOULD**/**SHOULD NOT**/**MAY** —
+  and both files open with an RFC 2119 reference statement. The hard-rules
+  summaries in `CLAUDE.md` and `AGENTS.md` were aligned. Language pass
+  only; rule numbering, thresholds, and semantics are unchanged (#15).
 
 - HR-008 now recognizes registration in any `wiki/index-*.md` sub-index, not
   only the root `wiki/index.md` (#9). The `vault-tools.sh lint` (and `doctor`)

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -104,10 +104,10 @@ All hard rules are defined in `.vault/rules/hard-rules.md`. Summary:
 8. **No file may exist in `wiki/` without a corresponding entry in `wiki/index.md`**.
 9. **Tags MUST use flat prefix notation**: `domain/engineering`, not nested hierarchies.
 10. **Binary files (images, PDFs) MUST be stored in `raw/`**, never in `wiki/` or `memory/`.
-11. **No agent may modify `.vault/rules/`, `.vault/hooks/`, or `.vault/scripts/`**. Governance changes require human PRs.
-12. **No agent may modify `CLAUDE.md`, `AGENTS.md`, or `CODEX.md`**. Agent instruction changes require human PRs.
-13. **No agent may modify `.github/` or `templates/`**. CI and template changes require human PRs.
-14. **Do not delete files from `wiki/` or `memory/`.** Set `status: archived` in frontmatter instead. Use `VAULT_ALLOW_DELETE=1` for cleanup.
+11. **Agents MUST NOT modify `.vault/rules/`, `.vault/hooks/`, or `.vault/scripts/`**. Governance changes require human PRs.
+12. **Agents MUST NOT modify `CLAUDE.md`, `AGENTS.md`, or `CODEX.md`**. Agent instruction changes require human PRs.
+13. **Agents MUST NOT modify `.github/` or `templates/`**. CI and template changes require human PRs.
+14. **Agents MUST NOT delete files from `wiki/` or `memory/`.** Set `status: archived` in frontmatter instead. Use `VAULT_ALLOW_DELETE=1` for cleanup.
 15. **Log files (`wiki/log.md`, `memory/logs/`) are append-only**. Deletions are rejected by HR-015. Set `LOG_EDIT_ALLOWED=1` to bypass for legitimate corrections.
 
 ### Soft Rules (Configurable — adapt to your workflow)