diff --git a/.vault/rules/hard-rules.md b/.vault/rules/hard-rules.md index 7f3909c..b60c893 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. @@ -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 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 c57c3ad..eb638a1 100644 --- 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 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)