sadp-harness 1.91

Structured AI Development Protocol — a governance harness for indefinite-horizon AI co-development

sadp-harness

Structured AI Development Protocol — a governance harness for indefinite-horizon AI co-development.

This is the PyPI packaging entry point. The full source, documentation, and provenance live at the parent repository: github.com/brownanan/acervator.

Install

pip install sadp-harness

The PyPI distribution name is sadp-harness; the Python import name is sadp:

import sadp
print(sadp.__version__)                # "1.91"

from sadp.cli import main
rc = main(["check"])                   # programmatic CLI

The console script sadp is registered globally on install:

sadp --help               # list subcommands
sadp --version            # print SADP version
sadp check                # run release-readiness gate
sadp scaffold --target /path  # bootstrap SADP into a fresh project
sadp hop --check          # validate HOP file schema
sadp mem-search "<query>" # search the episodic memory ledger
sadp doc-audit            # find documentation drift
sadp qa-status            # unified QA dashboard

What SADP is

A governance harness for AI co-development. Five-component architecture:

1. Atomic generational handoff — per-session HOP file with forward-looking ## NEXT SESSION header so the next session starts coherent
2. 60-rule core discipline layer (tier: "core" in RULE_REGISTRY.json) with LOCK / UNLOCK / SUSPEND state semantics. Cited canon: Tufte, Cleveland-McGill, Knaflic, Helland (idempotency, audit log), Nygard (circuit breaker), McCabe (complexity), Martin (SRP), Hunt & Thomas (fail loudly, DRY), WCAG 2.2 AA, Nielsen, KDE HIG, Material Design 3, IEEE 29148, Wikipedia WP:V/WP:NOR, Royal Society Nullius in verba
3. Project-overlay extension point (tier: "project_overlay" rules in your sadp/impl/IMPL-PROJECT.md) for domain-specific rules adopters declare for their own codebase
4. Administrative control surface — pre-bump release gate, PreToolUse hook, Stop forensic backstop, EDIT_LOG forensics, contextual anchors
5. Episodic memory ledger with token-scoring search (sadp mem-search) so accumulated lessons survive across sessions

Plus: evaluator subagent, architectural fitness functions, doc-audit instruments, unified QA dashboard, ground-truth test-count pin, version-bump cascade discipline.

Quickstart

# 1. Install
pip install sadp-harness

# 2. Bootstrap into your project
cd /path/to/your/project
sadp scaffold --target . --project-name myproject

# 3. The scaffold writes:
#    - sadp/config.json     (path overrides; defaults mirror Acervator shape)
#    - sadp/RULE_REGISTRY.json  (60 core rules, ready to enforce)
#    - sadp/EPISODIC_MEMORY.json  (empty ledger, you accumulate lessons)
#    - HOP.md                (your session-state document)
#    - AGENTS.md             (auto-generated from rule state)

# 4. Verify
sadp hop --check    # → [OK] HOP schema valid
sadp check          # → [OK] Release-ready (vX.Y.Z, N tests)

For per-project customization (changing HOP filename, MEM ledger path, changelog location, etc.) edit sadp/config.json. Every bundled tool resolves paths via sadp.config.Project — your overrides are honored.

Rule tiers

• Core (60 rules) — universal software-development discipline. Ships in every wheel. See sadp/SPEC-CORE.md for canonical text.
• Project overlay (17 illustrative rules in Acervator) — domain-specific rules (trading-engine internals, etc.) that DON'T ship in the wheel. Each adopter declares their own overlay rules in sadp/impl/IMPL-<PROJECT>.md.

The tier field in RULE_REGISTRY.json separates them. The wheel-publish tooling (tools/build_pypi_package.py) filters at stage time so only tier: "core" rules ship.

What's in the wheel

24 files, ~580 KB:

• sadp/{__init__,__main__,cli,config}.py — Python package + CLI dispatcher + path-discovery
• sadp/_tools/{check_release_readiness,hop_open,mem_search,doc_audit,doc_gap_audit,sadp_init,build_agents_md,qa_status}.py — 8 bundled subcommand implementations
• sadp/{SKILL.md,FIXED_SECTION_SCHEMAS.md,config.template.json,CHANGELOG.md,SPEC-CORE.md,RULE_REGISTRY.json} — canonical rule spec + schemas + scaffold templates

The wheel does NOT ship: Acervator's project-overlay rule bodies (sadp/impl/IMPL-ACERVATOR.md), the operator's MEM ledger (EPISODIC_MEMORY.json ships as empty scaffold), the forensic EDIT_LOG, HOPs, chronicle entries.

License

Apache 2.0 with patent grant. See LICENSE and NOTICE in the parent repository. SADP itself is fully open source; trading-specific inventions in the host repository (Acervator) are NOT inside the SADP grant.

Provenance

Built end-to-end from operating experience by Anthony L. Brown (Ekthelius the Accumulator) across 27 sessions and 398+ MEM entries of single-operator + single-Claude collaboration. The methodology emerged from real friction; structural patterns absorbed (with credit) from Anthropic's cwc-long-running-agents, AGENTS.md, the Anthropic Agent Skills specification, and Cavekit/Cavemem. Every rule cites at least one published canonical source (per R63 ERG); no rule was authored from unaided AI synthesis.