From a91aff31130257b7699b7e9ed964499befea5a93 Mon Sep 17 00:00:00 2001 From: galimba Date: Tue, 7 Jul 2026 16:56:28 +0200 Subject: [PATCH] docs(rules): adopt RFC 2119 keywords consistently across rule files Language-only pass: hard rules now state requirements exclusively with bolded MUST / MUST NOT, soft rules with SHOULD / SHOULD NOT / MAY, per RFC 2119, with the standard reference statement added at the top of both files. CLAUDE.md and AGENTS.md rule summaries aligned where they contradicted the reworded text. No rule semantics, numbering, or thresholds changed. Closes #15 Co-Authored-By: Claude Fable 5 --- .vault/rules/hard-rules.md | 41 +++++++++++++++-------------- .vault/rules/soft-rules.md | 54 ++++++++++++++++++++------------------ AGENTS.md | 8 +++--- CHANGELOG.md | 9 +++++++ CLAUDE.md | 8 +++--- 5 files changed, 68 insertions(+), 52 deletions(-) diff --git a/.vault/rules/hard-rules.md b/.vault/rules/hard-rules.md index 0985e7a..12da6f1 100644 --- 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. @@ -65,8 +68,8 @@ into `wiki/index-{{category}}.md` files with a root index linking 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. @@ -88,7 +91,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, @@ -100,9 +103,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. @@ -113,7 +116,7 @@ Agents MUST update this field whenever they modify page content ## HR-008: Index Registration -**Rule**: Every file in `wiki/` (except `index.md` and `log.md` themselves) MUST have a corresponding entry in `wiki/index.md`. The entry must include the file path and a one-line summary. +**Rule**: Every file in `wiki/` (except `index.md` and `log.md` themselves) **MUST** have a corresponding entry in `wiki/index.md`. The entry **MUST** include the file path and a one-line summary. **Rationale**: `wiki/index.md` is the primary retrieval mechanism. Agents read the index first to locate relevant pages. @@ -126,7 +129,7 @@ but is functionally absent from the knowledge base. ## 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. @@ -141,8 +144,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, @@ -158,7 +161,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. @@ -174,7 +177,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. @@ -190,7 +193,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. @@ -206,7 +209,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 @@ -238,8 +241,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 index 79fd4ab..1705025 100644 --- 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,13 +20,13 @@ ## 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. @@ -31,7 +34,7 @@ ## 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,8 +167,8 @@ 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. @@ -173,14 +176,15 @@ wiki ONLY if both conditions are met: 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 index e50eb24..21a3f18 100644 --- 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 index 635b357..ddd97e2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Changed + +- `.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). + ## [0.5.0] - 2026-07-07 ### Added diff --git a/CLAUDE.md b/CLAUDE.md index 46775b4..9347be7 100644 --- 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)