rules

Manage classification rules that assign document classes, retention policies that control archival behavior, source hierarchy rules that assign trust weights, and metadata control-plane rules for canonicalization-time query behavior. This command has the main rule/policy surface, nested source subcommands, and nested metadata subcommands.

Usage

bash

unsterwerx rules <SUBCOMMAND>

Subcommands

Subcommand	Description
`list`	List all classification rules
`add`	Add a new classification rule
`remove`	Remove (retire) a classification rule, or permanently delete with `--purge`
`reactivate`	Reactivate a previously retired rule
`policy`	Add a retention policy for a document class
`policies`	List retention policies
`resolve`	Resolve effective policy for a document, or preview cascade for a class (optionally scoped)
`assign-scope`	Assign a scope to a document (compare-and-set)
`source`	Manage source hierarchy trust weight rules
`metadata`	Manage metadata aliases, noise rules, concept config, settings, and rebuilds

rules list

Lists all active classification rules with their patterns and target classes.

bash

unsterwerx rules list

Classification Rules
══════════════════════════════════════════════════════════════
  [see] seed-contract        → contract        (active, p=0)
        filename: (?i)(contract|agreement|pogodba)
        content:  (?i)(hereby\s+agree|party\s+of\s+the|terms\s+and\s+conditions)
  [see] seed-cv              → cv              (active, p=0)
        filename: (?i)(cv|resume|curriculum)
        content:  (?i)(experience|education|skills|employment\s+history)
  [see] seed-government      → government      (active, p=0)
        filename: (?i)(government|official|gazette)
        content:  (?i)(public\s+notice|official\s+gazette|decree)
  [see] seed-invoice         → invoice         (active, p=0)
        filename: (?i)(invoice|faktura)
        content:  (?i)(total\s+due|amount\s+payable|invoice\s+number)
  [see] seed-legal           → legal           (active, p=0)
        filename: (?i)(legal|law|regulation)
        content:  (?i)(pursuant\s+to|article\s+\d|statutory|jurisdiction)
  [see] seed-report          → report          (active, p=0)
        filename: (?i)(report|analysis|summary)
        content:  (?i)(executive\s+summary|findings|recommendations)
══════════════════════════════════════════════════════════════

rules add

Adds a new classification rule with filename/content patterns, optional file-type gating, and optional metadata predicates.

bash

unsterwerx rules add [OPTIONS] --name <NAME> --class <CLASS>

Options

Option	Type	Default	Description
`--name`	string	required	Rule name
`--class`	string	required	Document class (e.g., invoice, contract, report)
`--filename-pattern`	regex		Filename pattern (regex)
`--file-type`	string		File type filter
`--content-pattern`	regex		Content pattern (regex)
`--priority`	integer	0	Priority (higher = evaluated first)
`--match-all`	flag		Require all patterns to match
`--scope`	string	`global`	Rule scope: `global`, `organization`, `division`, `user`
`--scope-id`	string		Scope identifier (fully-qualified path, e.g., `acme/sales`)
`--metadata-predicate`	string, repeatable		Metadata predicate in the form `<concept_key>=<op>:<values>`
`--metadata-date-predicate`	string, repeatable		Metadata date window in the form `<concept_key> from=<bound> to=<bound>`

Example

bash

unsterwerx rules add \
    --name "my-invoices" \
    --class invoice \
    --filename-pattern "(?i)invoice" \
    --content-pattern "(?i)(total\s+due|amount)" \
    --priority 10 \
    --match-all

Metadata predicates let Business Intelligence rules classify on semantic facts instead of only filename/content. For example:

bash

unsterwerx rules add \
    --name "word-docx-demo" \
    --class demo \
    --file-type docx \
    --metadata-predicate 'origin_software_name=equals:microsoft office word' \
    --metadata-date-predicate 'document_created_at from=2017-12-01 to=2017-12-31' \
    --match-all

Supported metadata predicate operators are:

equals
any_of
regex
exists

rules remove

Retires a classification rule (soft-delete). Retired rules stop matching documents but their classification history is preserved. Use --purge to permanently delete a rule and its classification records.

bash

unsterwerx rules remove [OPTIONS] <NAME>

Arguments

Argument	Required	Description
`NAME`	Yes	Rule name or ID

Options

Option	Short	Type	Default	Description
`--purge`		flag		Permanently delete the rule and its classification records instead of retiring

Example

bash

# Retire a rule (can be reactivated later)
unsterwerx rules remove my-invoices

# Permanently delete a rule and its classifications
unsterwerx rules remove --purge my-invoices

rules reactivate

Reactivates a previously retired classification rule.

bash

unsterwerx rules reactivate <NAME>

Arguments

Argument	Required	Description
`NAME`	Yes	Rule name or ID prefix

Example

bash

unsterwerx rules reactivate my-invoices

rules policy

Adds a retention policy for a document class. Policies control how long documents are retained and what happens at end-of-life.

bash

unsterwerx rules policy [OPTIONS] --class <CLASS> --name <NAME>

Options

Option	Type	Default	Description
`--class`	string	required	Document class
`--name`	string	required	Policy name
`--retention-years`	integer		Retention period in years
`--retention-days`	integer		Retention period in days (additive with years)
`--immutable`	flag		Mark as immutable (cannot be modified)
`--legal-hold`	flag		Enable legal hold (frozen for legal purposes)
`--action`	string	move	Archive action: `move`, `delete`, `keep`
`--scope`	string	global	Policy scope: `global`, `organization`, `division`, `user`
`--scope-id`	string		Scope identifier (required for non-global scopes)

Omit both retention fields for indefinite retention. A zero-valued retention component means immediate eligibility rather than “keep forever.”

Examples

bash

# Global retention policy
unsterwerx rules policy \
    --name "contract-retention" \
    --class contract \
    --retention-years 7 \
    --immutable \
    --action move

# Organization-scoped policy (tighter than global)
unsterwerx rules policy \
    --name "dod-contract-retention" \
    --class contract \
    --retention-years 10 \
    --immutable \
    --action keep \
    --scope organization \
    --scope-id "DoD"

Warning: Scoped policies cannot loosen constraints set by higher scopes. A division policy cannot set a shorter retention period than the organization policy.

rules policies

Lists all active retention policies.

bash

unsterwerx rules policies

Retention Policies
══════════════════════════════════════════════════════════════
  contract-retention   class=contract   scope=global            retain=7 years   IMMUTABLE action=move
  org-tighter-contract class=contract   scope=organization:DoD  retain=10 years  IMMUTABLE action=keep
  legal-hold           class=legal      scope=global            retain=10 years  IMMUTABLE action=keep [LEGAL HOLD]
══════════════════════════════════════════════════════════════

rules resolve

Resolves the effective policy for a specific document or previews the cascaded policy for a class. Omit --scope to preview global Business Intelligence defaults.

bash

unsterwerx rules resolve [OPTIONS]

Options

Option	Type	Description
`--document`	UUID	Document ID to resolve effective policy for
`--class`	string	Document class to preview cascaded policy for
`--scope`	string	Scope path for preview (e.g., `acme/sales`). Omit for global-only preview.

One of --document or --class is required. --document and --class/--scope are mutually exclusive. --scope requires --class.

Examples

bash

# Resolve effective policy for a document
unsterwerx rules resolve --document a1b2c3

# Preview global Business Intelligence defaults for a class
unsterwerx rules resolve --class tax

# Preview cascaded policy for a class in a specific scope
unsterwerx rules resolve --class contract --scope acme/sales

rules assign-scope

Assigns a scope to a document using compare-and-set semantics. Documents start with no scope (global). Once assigned, a scope cannot be changed to a different value. Only the same scope can be re-applied.

bash

unsterwerx rules assign-scope <DOCUMENT> --scope <SCOPE_PATH>

Arguments

Argument	Required	Description
`DOCUMENT`	Yes	Document ID or UUID prefix

Options

Option	Short	Type	Default	Description
`--scope`		string	required	Scope path (e.g., `acme`, `acme/sales`, `acme/sales/alice`)

Example

bash

unsterwerx rules assign-scope a1b2c3 --scope acme/sales

rules source

Manage source hierarchy trust weight rules. These rules assign trust weights to documents based on their source class.

rules source list

Lists all source hierarchy rules.

bash

unsterwerx rules source list

Source Hierarchy Rules
══════════════════════════════════════════════════════════════
  [seed-aca] academic        weight=5 p=0 (active)
  [seed-ai-] ai-generated    weight=1 p=0 (active)
  [seed-cur] curated         weight=2 p=0 (active)
  [seed-gov] government      weight=3 p=0 (active)
══════════════════════════════════════════════════════════════

rules source set

Creates or updates a source hierarchy rule.

bash

unsterwerx rules source set [OPTIONS] --trust-class <TRUST_CLASS> --weight <WEIGHT>

Option	Type	Default	Description
`--trust-class`	string	required	Trust class: `academic`, `government`, `curated`, `ai-generated`, or custom
`--weight`	integer	required	Trust weight (1–5, where 5 = highest trust)
`--pattern`	regex		Optional regex pattern to match source names
`--priority`	integer	0	Priority (higher = evaluated first)

bash

unsterwerx rules source set --trust-class academic --weight 5

rules source remove

Removes a source hierarchy rule.

bash

unsterwerx rules source remove <ID>

Argument	Required	Description
`ID`	Yes	Rule ID (prefix match supported)

rules source resolve

Resolves the effective trust weight for a document or recomputes all provenance records.

bash

unsterwerx rules source resolve [OPTIONS]

Option	Short	Type	Default	Description
`--document`		UUID prefix		Document ID or prefix to resolve
`--recompute`		flag		Recompute effective_weight for all provenance records

bash

unsterwerx rules source resolve --document a1b2c3

Weight Resolution for a1b2c3d4...
══════════════════════════════════════════════════════════════

rules metadata

Manages the metadata control plane: alias rewrite rules, noise rules, per-concept confidence overrides, control-plane defaults, and generation-aware rebuild operations.

rules metadata alias

Alias rules rewrite query-time inputs before lookup. They do not rewrite stored facts. The direction matters:

bash

unsterwerx rules metadata alias set \
    --concept-key document_author \
    --from "Department of Defense CIO" \
    --to "DoD CIO"

This means a query for Department of Defense CIO is canonicalized and rewritten to DoD CIO before search, metadata find, or metadata-aware classification predicates query the database.

Available subcommands:

rules metadata alias list
rules metadata alias set --concept-key <key> --from <synonym> --to <canonical> [--rebuild --document <id> | --rebuild --all]
rules metadata alias remove <id-or-prefix> [--rebuild --document <id> | --rebuild --all]
rules metadata alias resolve --concept-key <key> --value <raw>

rules metadata noise

Noise rules downgrade or suppress known-low-signal facts after extraction:

bash

unsterwerx rules metadata noise set \
    --concept-key origin_software_name \
    --match "Microsoft Office Word" \
    --action low-confidence \
    --rebuild --all

Actions:

low-confidence
suppress-facet

Available subcommands:

rules metadata noise list
rules metadata noise set ...
rules metadata noise remove <id-or-prefix> ...
rules metadata noise resolve --document <id> [--explain]

rules metadata concept-config

Overrides the default low-confidence threshold for a specific concept key:

bash

unsterwerx rules metadata concept-config set \
    --concept-key document_author \
    --low-confidence-threshold 0.95 \
    --rebuild --all

rules metadata settings

Shows or updates control-plane-wide defaults:

rules metadata settings show
rules metadata settings set --default-low-confidence-threshold 0.8 [--rebuild --document <id> | --rebuild --all]

rules metadata rebuild

Rebuilds semantic facts from already-stored extraction rows after alias/noise/config changes:

rules metadata rebuild --document <id>
rules metadata rebuild --all

Use rebuilds when you want the Shared Sandbox to recompute canonical values, low-confidence flags, and suppressed-facet state without re-reading source files. source=local class=curated weight=2 rule=seed-curated Matched trust-class rule ══════════════════════════════════════════════════════════════


## Notes

- Seed rules (prefixed `seed-`) are created automatically during database initialization and provide baseline classification patterns.
- Classification rules use Rust regex syntax. Patterns are case-insensitive when wrapped in `(?i)`.
- The policy cascade enforces that lower scopes (division, user) can only tighten constraints set by higher scopes (organization, global). See [Classification Guide](/docs/guides/classification/) for details.