cc-os/plugins/os-doc-hygiene/openspec/specs/lifecycle-rulebook/spec.md

Spec: lifecycle-rulebook

Purpose

Defines the global + optional per-project rulebook files that declare lifetime rules for known-clutter artifacts: their location and envelope, glob dialect, two-axis merge precedence, per-rule fields, validation behavior, the "unmatched means unmanaged" contract, the explicit IGNORE surface, and how the scanner walk consumes rules for pruning and lifecycle signal attachment.

Requirements

Requirement: Rulebook Locations and Envelope

The plugin SHALL ship a global rulebook at plugins/os-doc-hygiene/rulebook.json, resolved relative to plugin scripts, present in every project. A project MAY additionally provide a committed repo-root .dochygiene-rules.json override. Both files SHALL use the envelope {"schema_version": 1, "rules": [...]}. The project file MAY additionally carry a top-level nominations key (see the Nominations Memory requirement); the loader SHALL ignore unknown top-level keys, so the key is additive to schema_version 1. The per-project override SHALL NOT live under gitignored .cc-os/ — it SHALL be a committed, reviewable dotfile.

Scenario: Global rulebook is always present

• WHEN the rulebook loader runs in any project
• THEN it loads plugins/os-doc-hygiene/rulebook.json resolved relative to the plugin scripts directory

Scenario: Per-project override is optional and committed

• WHEN a project has no .dochygiene-rules.json at its repo root
• THEN the loader proceeds using only the global rulebook, and when the file is present it is read as a committed, reviewable file, never from .cc-os/

Scenario: Both files share one envelope shape

• WHEN either the global rulebook or a project override is loaded
• THEN it is validated against the envelope {"schema_version": 1, "rules": [...]}

Scenario: A nominations key does not disturb the v1 loader

• WHEN a project .dochygiene-rules.json carries a top-level nominations key alongside rules
• THEN rulebook.py loads the rules array exactly as before, ignoring the unknown top-level key without warning or error

Requirement: Glob Dialect Is glob.translate

Rule glob patterns SHALL be compiled using stdlib glob.translate(pattern, recursive=True, include_hidden=True) (Python ≥ 3.13). Patterns SHALL be interpreted as repo-root-relative, and ** SHALL match recursively. Each rule's glob SHALL be compiled once at rulebook load time, not per matched path.

Scenario: Recursive double-star matches subtrees

• WHEN a rule's glob is autoresearch/*/**
• THEN it matches any file at any depth under any immediate subdirectory of autoresearch/

Scenario: Hidden files are matched when the pattern implies them

• WHEN a rule's glob targets a dotfile path
• THEN include_hidden=True semantics apply and the dotfile is matchable

Scenario: Compilation happens once per load

• WHEN the rulebook loader parses the rules array
• THEN each rule's glob is compiled to a matcher exactly once, and that compiled matcher is reused for every path checked during the run

Requirement: Two-Axis Precedence with Add-Only Merge

The rulebook loader SHALL merge the project override over the global rulebook using add-only semantics: project rules are appended to, and never replace or delete, global rules. Precedence for a given path SHALL resolve in this order: project file-rule > project directory-rule > global file-rule > global directory-rule. Ties within the same precedence tier SHALL be broken first by longest glob pattern, then by last-defined order. A project SHALL neutralize a global rule only by adding a shadowing rule with lifetime: "keep" at equal-or-higher precedence; there SHALL be no rule-removal mechanism.

Scenario: Project file-rule outranks every other tier

• WHEN a path matches both a project file-rule and a global directory-rule
• THEN the project file-rule's fields govern

Scenario: Ties broken by longest pattern then last-defined

• WHEN two rules in the same precedence tier match the same path with different-length globs
• THEN the rule with the longer glob pattern governs; if the glob lengths are equal, the rule defined later in its rules array governs

Scenario: Neutralizing a global rule via keep-shadowing

• WHEN a project wants to exempt a path from a global delete rule
• THEN it adds a project rule matching that path with lifetime: "keep", and no mechanism exists to remove or edit the global rule itself

Scenario: Merge never deletes a global rule

• WHEN the project override is loaded alongside the global rulebook
• THEN every global rule remains present and evaluable; the merge only adds project rules on top

Requirement: Per-Rule Fields

A rule SHALL support the fields glob, lifetime (one of keep, temporary, delete-once-served), extract (boolean modifier), served_when (free text, classifier hint), served_when_path (deterministic sibling of served_when), retain_recent (default 3), max_age_days (default 3), confirm (boolean, human-settable-only escape hatch), confirmed_by (human or a strong-model identifier), confirmed_on, source, and note. A rule SHALL NOT support a propagate_ignore field in any form. A rule that matches no path yet is undefined behavior only in the sense that unmatched files receive no lifetime at all and flow through existing signals unchanged — unmatched SHALL always mean unmanaged, never an implicit lifetime.

Scenario: Defaults apply when retain_recent/max_age_days are omitted

• WHEN a temporary-lifetime rule omits retain_recent and max_age_days
• THEN the loader applies retain_recent = 3 and max_age_days = 3

Scenario: confirm:true may only be set by a human

• WHEN a rule is validated
• THEN a rule with confirm: true is accepted only if it is not proposed by a model in the same validation pass as an unconfirmed state — a model-authored rule proposal SHALL NOT itself set confirm: true; it may only recommend that a human set it

Scenario: propagate_ignore is rejected as an unknown field

• WHEN a rule in either rulebook file contains a propagate_ignore field
• THEN the loader treats it as an unrecognized field under the rule's validation (skip-and-warn, per the Validation requirement), since no such field is part of the schema

Scenario: Unmatched files receive no lifetime

• WHEN a file matches no rule in either rulebook
• THEN the rulebook query returns no match for that path, and the file flows through the existing (non-lifecycle) scanner signals unchanged, becoming a :calibrate candidate

Requirement: Skip-and-Warn Validation, Hard-Fail Only on Structural Errors

The rulebook loader SHALL skip and warn on a per-rule basis for any rule that is invalid or lacks confirmed_by — such a rule SHALL be loaded but marked inactive and SHALL never contribute a lifecycle signal, while the rest of the rulebook continues to load and function. The loader SHALL hard-fail (non-zero exit / raised error) only for unparseable JSON or an unrecognized schema_version.

Scenario: A rule missing confirmed_by is skipped, not fatal

• WHEN the rulebook contains one rule without confirmed_by and nine valid rules
• THEN the loader loads all ten rules, marks the one missing confirmed_by inactive (it never emits a signal), and the other nine function normally

Scenario: Unparseable JSON hard-fails

• WHEN either rulebook file is not valid JSON
• THEN the loader raises a hard failure and does not proceed with a partial rulebook

Scenario: Unknown schema_version hard-fails

• WHEN a rulebook file declares a schema_version the loader does not recognize
• THEN the loader raises a hard failure

Requirement: Unmatched Means Unmanaged

Files that match no rule in either rulebook SHALL receive no lifecycle signal and SHALL NOT be deleted, extracted, or otherwise treated as lifecycle-managed by any component of this change. They remain visible only through the existing stale/bloat signal pipeline and are the candidate pool for :calibrate.

Scenario: No rule match means no lifecycle behavior

• WHEN a file matches no rulebook rule
• THEN no delete or extract-then-delete op is ever proposed for it on lifecycle grounds alone

Requirement: IGNORE Surface Is an Explicit Seed List, Never Inferred from .gitignore

The rulebook SHALL define an explicit IGNORE surface as directory rules with no lifetime (paths never walked at all, distinct from keep, which is walked and reported but never deleted). The seed IGNORE members SHALL include graphify-out/** and .dochygiene/**, plus any entries needed to cover the plugin's actual current state directory (.cc-os/**, already covered by the scanner's pre-existing hardcoded self-exclusion — see the doc-check spec). The IGNORE surface SHALL NEVER be inferred from .gitignore — a gitignored path is neither automatically deletable nor automatically keepable.

Scenario: graphify-out is never walked

• WHEN the scanner walks a project containing graphify-out/
• THEN no file beneath graphify-out/ is opened, and no shortlist or signal entry is produced for it or its contents

Scenario: .dochygiene legacy state dir is never walked

• WHEN the scanner encounters .dochygiene/ in a project that has not migrated to .cc-os/dochygiene/
• THEN the directory is treated as IGNORE surface and never walked

Scenario: gitignored is not treated as IGNORE surface

• WHEN a path is listed in .gitignore but is not one of the explicit IGNORE seed members
• THEN the scanner walks it normally per its other rules — being gitignored alone neither excludes it from the walk nor exempts it from deletion

Requirement: Directory-Rule Walk Pruning

When a directory-rule (a lifecycle rule whose glob covers a subtree) matches a directory during the scanner walk, the scanner SHALL prune the walk at that directory: no file beneath it SHALL be opened or read. For directory rules carrying a real lifetime (temporary or delete-once-served), the scanner SHALL emit exactly one aggregate shortlist/signal entry for the directory path itself, carrying the lifecycle signal (rule reference, lifetime, and served_when/served_when_path). For IGNORE-surface directory rules (no lifetime), the scanner SHALL emit no entry at all.

Scenario: A temporary directory rule prunes and emits one aggregate entry

• WHEN autoresearch/run-2026-07-01/ matches a directory rule with lifetime: temporary
• THEN the scanner does not open any file inside that directory and emits exactly one shortlist entry for the directory path carrying the lifecycle signal

Scenario: An IGNORE-surface directory rule prunes with no entry

• WHEN graphify-out/ matches the IGNORE-surface rule
• THEN the scanner does not open any file inside it and produces no shortlist or signal entry for it

Requirement: Lifecycle Signal Attachment on File-Rule Matches

When a file-rule matches a path not caught by a directory-rule prune, the scanner SHALL attach a lifecycle signal (rule reference, lifetime, served_when/served_when_path) to that file's shortlist entry, alongside any pre-existing objective signals for the same file. The lifecycle signal SHALL be a new signal class consumed by the classification subagent like any other signal.

Scenario: A file-rule match adds a lifecycle signal without displacing existing signals

• WHEN HANDOFF-2026-07-01.md matches a file-rule with lifetime: delete-once-served and also has an existing broken-reference signal
• THEN its shortlist entry carries both the lifecycle signal and the pre-existing broken-reference signal

Requirement: Nominations Memory Lives in the Project Rules File

The project .dochygiene-rules.json MAY carry a top-level nominations key holding exactly two lists: consults (open questions — entries with glob, question, evidence, cluster_key, asked_on, and deliberately NO lifetime) and rejected (settled "no" answers — entries with glob, lifetime, why, optional consider_instead, rejected_by ("judge" or "human"), judged_on). The nominations key SHALL never affect which files the rulebook governs — only entries in rules decide that. rulebook.py SHALL remain nomination-unaware; only the calibrate helpers read the key, and the calibrate reader SHALL warn on unrecognized nomination fields, mirroring the rules array's unknown-field discipline. Rejected entries and exact-path singleton keep rules SHALL exit only by hand-deletion (removals stay HITL with recorded reasoning); no automated revisit path SHALL exist.

Scenario: Nominations never filter files

• WHEN the scanner or rulebook resolves the governing rule for a path that only a nominations entry's glob matches
• THEN the path is treated as unmatched/unmanaged — nominations carry no lifecycle authority

Scenario: Consult entries carry no lifetime

• WHEN a consult entry is written to nominations.consults
• THEN it records glob, question, evidence, cluster_key, asked_on and no lifetime field — presence in the list means open, with no status field

Scenario: Unrecognized nomination fields warn in the calibrate reader

• WHEN the calibrate helpers read a nominations entry containing an unknown field
• THEN a warning is emitted and the field is preserved, never silently dropped

Scenario: A rejection leaves only by hand-deletion

• WHEN a calibration pass runs against a rules file containing a stale rejection
• THEN no automated path removes or expires the entry; it is removed only by explicit human edit

Requirement: Canonical Writer-Enforced Ordering

Every code path that serializes .dochygiene-rules.json SHALL write through one canonical writer that emits: rules grouped by lifetime tier in the order delete-once-served, temporary, keep, glob-sorted within each group; nominations after rules; consults before rejected, each glob-sorted. The writer SHALL be idempotent (canonicalizing an already-canonical file is a no-op) and SHALL round-trip unknown fields with a warning rather than dropping them. Ordering SHALL NOT be enforced by any hook; hand edits re-canonicalize on the next write.

Scenario: Writes are grouped and sorted canonically

• WHEN the writer serializes a rules file containing rules of all three tiers plus nominations
• THEN the output orders rules delete-once-served → temporary → keep with globs sorted within each group, and nominations follows rules with consults before rejected, each list glob-sorted

Scenario: Canonicalization is idempotent

• WHEN the writer serializes a file it previously wrote, unchanged
• THEN the output is byte-identical

Scenario: A hand-edited file re-canonicalizes on the next write

• WHEN a human appends a rule out of tier order and a later calibrate run persists a new entry
• THEN the whole file is rewritten in canonical order in that write, with no hook involved in the interim