Metadata-Version: 2.4
Name: cognitive-governance
Version: 0.1.0
Summary: Traits, not prompts: persistent dispositions above your model — anti-manipulation governance, investigative drive, moral drift detection. Deterministic, disclosed, zero dependencies.
License: Apache-2.0
Classifier: License :: OSI Approved :: Apache Software License
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Dynamic: license-file

# Cognitive Governance

[![tests](https://github.com/davedepew/cognitive-governance/actions/workflows/tests.yml/badge.svg)](https://github.com/davedepew/cognitive-governance/actions/workflows/tests.yml)

**Traits, not prompts: persistent dispositions above your model — anti-manipulation
governance, investigative drive, moral drift detection — deterministic, disclosed, fail-open.**

A capability is what a system *can* do. A cognitive trait is what it is *inclined to do
automatically*. This package gives an LLM system a small set of always-on, deterministic
dispositions that run above the model on every reply:

| Module | Question it asks |
|---|---|
| `amg` — Anti-Manipulation Governance | Is this influence fair? Is the reader's agency preserved? |
| `investigative_drive` | What should become known next? (sensitivity-weighted priority) |
| `investigation_ledger` | Which open questions must survive restarts and days? |
| `self_deception` | Firm conclusion on thin evidence? Identity-protective reasoning? |
| `skepticism` | Strong language, weak support? |
| `integrity` | Authority claims, fabrication suggestions, pressure-as-consent? |
| `moral_drift` | Is "just this once" eroding a written principle over time? |

All deterministic Python — no model calls, microseconds per evaluation, zero runtime
dependencies. Compose them with `governance_pipeline(text)` or use any module alone.

```python
from cognitive_traits import governance_pipeline

r = governance_pipeline("Trust me — everyone knows you must expand now.")
r["amg"]["level"]        # 0 clean · 1 advisory · 2 revision suggested · 3 block-worthy
r["delivery"]            # {"allow": ..., "require_revision": ..., "block": ...}
r["investigative_drive"] # what the text suggests should become known next
```

The principle behind AMG: **change beliefs through evidence and reasoning, never by
exploiting emotional, cognitive, or social vulnerabilities.** The detectors flag
love-bombing, dependency-building, manufactured urgency, social pressure, and their
relatives — in your system's own drafts, before they ship.

## Moral drift: written principles only

`moral_drift` watches for incremental exception language ("just this once", "the rule
can slide today") against **written principles you supply** — see `PRINCIPLES.md` for
the shipped examples (truth ≠ authority, pressure ≠ consent, prefer unknown to
unjustified certainty, prediction ≠ authority, no fabricated facts…). Unknown principle
ids are rejected: the monitor cannot invent morals. Three exceptions against the same
principle inside the window raises a pattern flag — erosion made visible before it
becomes culture.

**Named residual:** the passive `scan()` is exact-phrase matching — low false positives
by design, low recall on paraphrase. The primary mechanism is explicitly recorded
exceptions plus `pattern_report()`. Grow the lexicon from real observed misses, never
from imagination.

## The investigation ledger

Curiosity that survives restarts: open questions persist to disk with priority,
sensitivity, missing evidence, and hypotheses. `resolve()` demands a real resolution
("receipt, not vibes"); `abandon()` demands a reason. `top_open()` returns
footer-ready lines for a UI. State lives in `$COGNITIVE_TRAITS_STATE`
(default `./.cognitive_traits/`).

## Prove it yourself

```bash
python src/cognitive_traits/selftest.py
python tests/test_investigation_ledger.py
python tests/test_moral_drift.py
```

## Sibling projects

Part of a trilogy extracted from the same production system, deliberately separate
packages — composed in a pipeline, never merged:

- [Evidence-Binding Compiler](https://github.com/davedepew/evidence-binding-compiler)
  (*an unsourced claim is a build error*): EBC governs whether claims are **supported**;
  this package governs whether influence is **fair** and attention is **well-aimed**.
  (`governance_pipeline(text, run_ebc=True)` uses EBC when installed.)
- [Trust Skeleton](https://github.com/davedepew/trust-skeleton): a fixed-order,
  fail-closed contract for how a high-stakes **report** is structured. Its `emotional_bias`
  and `manipulation_level` inputs are exactly what this package's detectors produce.

Facts bound to evidence, reasoning governed, reports carrying their own epistemics.

## What this does NOT do

- It does not make a model ethical; it makes specific dishonesty shapes visible.
- Detectors are deterministic lexicons: measured recall limits, disclosed above.
- It never blocks silently — every level-3 verdict carries its rationale.
- It is not a substitute for the human principal's judgment; it defends it.

## Provenance

Extracted from a private production system where these traits run live on every reply
of a governed personal-AI sounding board, cross-verified with seeded adversarial
probes. This repository is a severed snapshot: no production identifiers, paths, or
data ship with it.

The origin story is written up here:
[Traits, Not Prompts](https://www.davedepew.com/traits-not-prompts/).

## License

Apache 2.0 — see `LICENSE`. The license does not grant rights to the project's names
or branding (see `NOTICE`).

## Status

V0.1. Issues welcome — an attack that beats a detector is the most valuable report
there is; pull requests closed during v0.x (see `CONTRIBUTING.md`).
