rootsign 0.1.1__tar.gz

rootsign-0.1.1/.env.example

@@ -0,0 +1,38 @@
+# ---------------------------------------------------------------------------
+# Store-side infra config (read by rootsign.config.Settings — no prefix).
+# These describe the PostgreSQL/TimescaleDB instance the storage layer
+# connects to. Defaults assume the bundled docker-compose db service.
+# ---------------------------------------------------------------------------
+DATABASE_URL=postgresql+asyncpg://rootsign:rootsign@localhost:5432/rootsign_dev
+DATABASE_URL_SYNC=postgresql+psycopg2://rootsign:rootsign@localhost:5432/rootsign_dev
+TEST_DATABASE_URL=postgresql+asyncpg://rootsign:rootsign@localhost:5432/rootsign_test
+TEST_DATABASE_URL_SYNC=postgresql+psycopg2://rootsign:rootsign@localhost:5432/rootsign_test
+DB_POOL_SIZE=10
+DB_MAX_OVERFLOW=20
+DB_POOL_TIMEOUT=30
+
+# ---------------------------------------------------------------------------
+# RootSign SDK config (read by rootsign.sdk.config.SDKSettings, prefix
+# ROOTSIGN_). User-facing — the developer using @rootsign.trace sets these.
+# ---------------------------------------------------------------------------
+
+# Transport: 'local' calls IngestHandler in-process (Phase 1 default).
+# 'cloud' would POST to the hosted backend, but Phase 1 stubs that path —
+# HttpIngestClient raises NotImplementedError until Phase 2.
+ROOTSIGN_BACKEND=local
+# ROOTSIGN_CLOUD_URL=https://ingest.getprovidex.com/v1
+# ROOTSIGN_API_KEY=your-api-key-here
+
+# Capture per-step Decision records (the agent's reasoning). Off by default
+# because Decision payloads are the largest and most PII-sensitive surface.
+# Enabling in production requires explicit user-consent acknowledgement.
+ROOTSIGN_CAPTURE_DECISIONS=false
+
+# Write-ahead log for events that failed ingest (network blip, DB down).
+# The decorator drains this on the next successful call. Default: ~/.rootsign/wal
+ROOTSIGN_WAL_PATH=~/.rootsign/wal
+
+# Retry policy for HttpIngestClient (Phase 2 — unused in Phase 1).
+ROOTSIGN_MAX_RETRIES=3
+ROOTSIGN_RETRY_BASE_DELAY=0.1
+ROOTSIGN_RETRY_MAX_DELAY=5.0

rootsign-0.1.1/.github/CLA_SIGNED.md

@@ -0,0 +1,7 @@
+# CLA Signatures
+
+This file records contributors who have signed the [Contributor License Agreement](../CLA.md). New contributors are added automatically by the CLA Assistant bot the first time they comment the sign-off line on a PR.
+
+| GitHub handle | Date       | Commit  |
+|---------------|------------|---------|
+| @oabolade     | 2026-05-01 | initial |

rootsign-0.1.1/.github/CODEOWNERS

@@ -0,0 +1,9 @@
+# RootSign CODEOWNERS
+# These owners are automatically requested for review on PRs.
+
+*                   @oabolade
+/rootsign/          @oabolade
+/tests/             @oabolade
+/docs/adr/          @oabolade
+/alembic/           @oabolade
+/.github/           @oabolade

rootsign-0.1.1/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,33 @@
+name: Bug report
+description: Something is not working as described in the spec
+labels: [bug, needs-triage]
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: What happened?
+      description: Describe the bug. Include the exact error message.
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Minimal reproduction
+      description: Shortest code that reproduces the issue.
+      render: python
+    validations:
+      required: true
+  - type: dropdown
+    id: framework
+    attributes:
+      label: Agent framework
+      options: [LangGraph, CrewAI, AutoGen, Custom, Not applicable]
+    validations:
+      required: true
+  - type: input
+    id: versions
+    attributes:
+      label: Versions
+      placeholder: rootsign==0.1.0, langgraph==0.2.1, python==3.11
+    validations:
+      required: true

rootsign-0.1.1/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,34 @@
+name: Feature request
+description: Suggest a new capability or improvement
+labels: [enhancement, needs-triage]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem does this solve?
+      description: Describe the limitation or gap you are experiencing.
+    validations:
+      required: true
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed solution
+      description: How would you like this to work?
+    validations:
+      required: true
+  - type: dropdown
+    id: phase
+    attributes:
+      label: Which product phase does this relate to?
+      options:
+        - Phase 1 (SDK capture)
+        - Phase 2 (Compliance dashboard)
+        - Phase 3 (Enterprise enforcement)
+        - Phase 4 (Cross-platform governance)
+        - Not sure
+  - type: checkboxes
+    id: contribute
+    attributes:
+      label: Contribution
+      options:
+        - label: I am willing to implement this

rootsign-0.1.1/.github/ISSUE_TEMPLATE/framework_integration.yml

@@ -0,0 +1,26 @@
+name: Framework integration request
+description: Request support for a new agent framework
+labels: [framework-integration, enhancement]
+body:
+  - type: input
+    id: framework
+    attributes:
+      label: Framework name and link
+      placeholder: 'LlamaIndex — https://github.com/run-llama/llama_index'
+    validations:
+      required: true
+  - type: textarea
+    id: tool_call
+    attributes:
+      label: How does this framework call tools?
+      description: Paste a minimal example of a tool call in this framework.
+      render: python
+    validations:
+      required: true
+  - type: checkboxes
+    id: willing
+    attributes:
+      label: Contribution
+      options:
+        - label: I am willing to implement this integration
+        - label: I can provide a real pipeline for contract testing

rootsign-0.1.1/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,27 @@
+## Summary
+<!-- One sentence: what does this PR do? -->
+
+## Related issue
+Closes #
+
+## Type of change
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Framework integration
+- [ ] Documentation
+- [ ] Test coverage
+
+## Checklist
+- [ ] All existing tests pass (`pytest tests/ -v`)
+- [ ] New code has test coverage >= 90%
+- [ ] Overall coverage stays >= 85% (enforced by `pyproject.toml`)
+- [ ] No changes to canonical hash spec (or new ADR filed if yes — see [ADR-001](../docs/adr/ADR-001-hash-canonical-spec.md))
+- [ ] `ruff check .` and `ruff format .` pass
+- [ ] CONTRIBUTING.md commit message format followed
+- [ ] CLA signed (bot will check automatically)
+
+## Testing done
+<!-- List specific test cases you ran manually -->
+
+## Notes for reviewer
+<!-- Anything the reviewer should pay special attention to -->

rootsign-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,153 @@
+name: CI
+
+on:
+  push:
+    branches: [main, 'feat/**', 'fix/**', 'test/**', 'docs/**']
+  pull_request:
+    branches: [main]
+
+jobs:
+  unit-tests:
+    name: Unit tests (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.11', '3.12']
+    services:
+      # The session-scoped _bootstrap_test_db fixture needs a real Postgres
+      # even for unit tests (it runs alembic against rootsign_test before
+      # collection). See feedback_phase0_discrepancies — we keep the
+      # alembic-based test DB rather than Base.metadata.create_all so the
+      # actions table stays a real TimescaleDB hypertable.
+      timescaledb:
+        image: timescale/timescaledb:latest-pg16
+        env:
+          POSTGRES_DB: rootsign_dev
+          POSTGRES_USER: rootsign
+          POSTGRES_PASSWORD: rootsign
+        ports: ['5432:5432']
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 10
+    env:
+      DATABASE_URL: postgresql+asyncpg://rootsign:rootsign@localhost:5432/rootsign_dev
+      DATABASE_URL_SYNC: postgresql+psycopg2://rootsign:rootsign@localhost:5432/rootsign_dev
+      TEST_DATABASE_URL: postgresql+asyncpg://rootsign:rootsign@localhost:5432/rootsign_test
+      TEST_DATABASE_URL_SYNC: postgresql+psycopg2://rootsign:rootsign@localhost:5432/rootsign_test
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: pip install -e '.[dev]'
+      - name: Wait for Postgres
+        run: |
+          for _ in $(seq 1 30); do
+            pg_isready -h localhost -U rootsign -d rootsign_dev && break
+            sleep 1
+          done
+      - name: Bootstrap rootsign_test
+        run: |
+          PGPASSWORD=rootsign psql -h localhost -U rootsign -d rootsign_dev \
+            -c "CREATE DATABASE rootsign_test OWNER rootsign;" || true
+          PGPASSWORD=rootsign psql -h localhost -U rootsign -d rootsign_test \
+            -c "CREATE EXTENSION IF NOT EXISTS timescaledb;"
+      - name: Unit tests
+        run: pytest tests/unit/ -v
+
+  integration-tests:
+    name: Integration tests (Python 3.12)
+    runs-on: ubuntu-latest
+    services:
+      timescaledb:
+        image: timescale/timescaledb:latest-pg16
+        env:
+          POSTGRES_DB: rootsign_dev
+          POSTGRES_USER: rootsign
+          POSTGRES_PASSWORD: rootsign
+        ports: ['5432:5432']
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 10
+    env:
+      DATABASE_URL: postgresql+asyncpg://rootsign:rootsign@localhost:5432/rootsign_dev
+      DATABASE_URL_SYNC: postgresql+psycopg2://rootsign:rootsign@localhost:5432/rootsign_dev
+      TEST_DATABASE_URL: postgresql+asyncpg://rootsign:rootsign@localhost:5432/rootsign_test
+      TEST_DATABASE_URL_SYNC: postgresql+psycopg2://rootsign:rootsign@localhost:5432/rootsign_test
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.12'
+      - run: pip install -e '.[dev]'
+      - name: Bootstrap rootsign_test
+        run: |
+          PGPASSWORD=rootsign psql -h localhost -U rootsign -d rootsign_dev \
+            -c "CREATE DATABASE rootsign_test OWNER rootsign;" || true
+          PGPASSWORD=rootsign psql -h localhost -U rootsign -d rootsign_test \
+            -c "CREATE EXTENSION IF NOT EXISTS timescaledb;"
+      - name: alembic upgrade head
+        run: alembic upgrade head
+      - name: Integration tests
+        run: pytest tests/integration/ -v
+
+  framework-contract-langgraph:
+    # ADR-003 / Sprint 2: framework contract tests are MANDATORY — this job
+    # must pass on every PR before merge. Sprint 2 filled the contract suite
+    # in tests/contract/langgraph/ (see ADR-004 for the interception design).
+    #
+    # Contract tests use a mock IngestClient and never touch the DB, so this
+    # job intentionally runs WITHOUT a Postgres service. The
+    # ROOTSIGN_SKIP_DB_BOOTSTRAP env var tells the session-autouse fixture
+    # in tests/conftest.py to skip alembic / DB connect at session start.
+    name: LangGraph contract (langgraph ~=${{ matrix.langgraph-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        langgraph-version: ['0.1', '0.2']
+    env:
+      ROOTSIGN_SKIP_DB_BOOTSTRAP: '1'
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.12'
+      - name: Install with langgraph extra
+        run: pip install -e '.[dev,langgraph]' "langgraph~=${{ matrix.langgraph-version }}"
+      - name: Contract tests
+        run: pytest tests/contract/langgraph/ -v
+
+  framework-contract-crewai:
+    # ADR-005 / Sprint 3: framework contract tests for CrewAI are MANDATORY —
+    # this job must pass on every PR before merge. Same pattern as the
+    # langgraph job above: mock IngestClient, no DB, ROOTSIGN_SKIP_DB_BOOTSTRAP.
+    #
+    # Sprint 4 (S4-TASK 10): added '1.0' to lock the duck-typing strategy
+    # against the 1.x line ahead of the Show HN post. Local run against
+    # crewai 1.6.1 had all 13 contract tests green — the ADR-005
+    # heuristic (name + _run callable) survives 1.x's BaseTool refactor
+    # because we never imported the class, only the shape.
+    name: CrewAI contract (crewai ~=${{ matrix.crewai-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        crewai-version: ['0.28', '0.40', '1.0']
+    env:
+      ROOTSIGN_SKIP_DB_BOOTSTRAP: '1'
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.12'
+      - name: Install with crewai extra
+        run: pip install -e '.[dev,crewai]' "crewai~=${{ matrix.crewai-version }}"
+      - name: Contract tests
+        run: pytest tests/contract/crewai/ -v

rootsign-0.1.1/.gitignore

@@ -0,0 +1,65 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+.venv/
+venv/
+env/
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+.tox/
+.mypy_cache/
+.ruff_cache/
+.dmypy.json
+.env
+.env.local
+.idea/
+# .vscode: gitignore everything except shared workspace files
+.vscode/*
+!.vscode/settings.json
+!.vscode/extensions.json
+!.vscode/tasks.json
+*.swp
+*.swo
+.DS_Store
+*.log
+pip-log.txt
+pip-delete-this-directory.txt
+.python-version
+
+# Confidential coding-agent sprint briefings (per CLAUDE.md / memory
+# feedback_never_commit_internal_specs). These are dropped into the
+# repo root for the coding agent to READ but must NEVER be committed.
+# Memory reference: feedback_never_commit_internal_specs.md.
+AGENTS_Phase*.md
+AGENTS_PRD*.md
+RootSign_Phase*.docx
+RootSign_Phase*.md
+RootSign_PRD*.docx
+RootSign_PRD*.md
+ProvidexAI_Phase*.docx
+ProvidexAI_Phase*.md
+ProvidexAI_PRD*.docx
+ProvidexAI_PRD*.md
+
+# Code-quality / security review artifacts the founder runs locally.
+# Track them in a private notes location, not in-tree.
+rootsign_review.md
+
+# Local-only memory backups and ephemeral sample files dropped into the
+# repo root for the coding agent to read during a session. See CLAUDE.md
+# top section. MEMORY.md is the working memory index — never committed.
+MEMORY.md
+MEMORY_*.md
+Sample_*.md
+Sample_*.py
+Sample_*.docx

rootsign-0.1.1/.vscode/settings.json

@@ -0,0 +1,9 @@
+{
+  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
+  "python.testing.pytestEnabled": true,
+  "python.testing.unittestEnabled": false,
+  "python.testing.pytestArgs": ["tests"],
+  "[python]": {
+    "editor.defaultFormatter": "charliermarsh.ruff"
+  }
+}

rootsign-0.1.1/CLA.md

@@ -0,0 +1,15 @@
+# RootSign Contributor License Agreement
+
+By signing this agreement, you (the Contributor) grant Providex AI Inc. (the Project) a perpetual, worldwide, non-exclusive, royalty-free license to use, reproduce, modify, distribute, and sublicense your Contributions as part of the Project.
+
+You confirm that:
+
+1. You have the legal right to grant this license.
+2. Your Contribution is your original work, or you have sufficient rights to submit it.
+3. You understand the Project may relicense your Contribution under other terms in the future, including commercial licenses.
+
+You retain copyright ownership of your Contributions.
+
+This agreement does not affect your ability to use your own Contributions for any purpose.
+
+**To sign:** comment `I have read the CLA Document and I hereby sign the CLA` on any pull request. The CLA Assistant bot will record your signature.

rootsign-0.1.1/CLAUDE.md

@@ -0,0 +1,90 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## NEVER commit or push project/sprint artifacts
+
+Sprint plans, agent guides, internal audits, memory snapshots, and similar working documents **must stay local**. They are gitignored as a backstop, but the rule is the rule regardless of whether `.gitignore` catches a given filename:
+
+- `AGENTS*.md`, `AGENTS_Phase*.md`, `RootSign_Phase*.{md,docx}`, `ProvidexAI_Phase*.{md,docx}`
+- `MEMORY.md` and anything under a `memory/` directory
+- `rootsign_review.md` and other founder-run audit artifacts
+
+If a new artifact like this gets created during a session, treat it as local-only by default. Do not `git add`, do not stage, do not include in commits. If a `git add -A` / `git add .` would sweep one in, switch to per-file staging. If a similar file pattern appears that isn't already gitignored, add the pattern to `.gitignore` in the same change.
+
+**Why:** these documents contain unreleased product strategy, audit findings, and pre-decision context. A Sprint 4 history-rewrite was needed once to scrub an accidentally-tracked sprint plan — the gitignore patterns added in commit 128cec5 exist as a mechanical backstop. The rule is to never need that backstop.
+
+## Where the code actually lives
+
+The Python project is `phase0/` (this directory). The parent `turbo/` is just a workspace wrapper. All paths below are relative to `phase0/`.
+
+## Dev environment
+
+CONTRIBUTING.md has the full setup. The non-obvious bits:
+
+- **Always run `python -m pytest`, never bare `pytest`.** A brew-installed `pytest` shadows the venv binary and silently runs under the system interpreter — produces `ModuleNotFoundError: sqlalchemy` and similar.
+- **Even unit tests need a running database.** `tests/conftest.py` has a session-scoped `_bootstrap_test_db` fixture that runs alembic before any test collection. Start the DB first: `rootsign-admin start-db` (or `docker-compose up -d db` in-repo).
+- **Schema bootstrap:** `rootsign-admin init` applies migrations. Idempotent. `--reset` drops and recreates the public schema (no confirmation prompt — be careful).
+- **Single test:** `python -m pytest tests/integration/test_show_hn_quickstart.py::TestShowHNQuickstart::test_readme_quickstart_end_to_end -v`
+- **Test markers:** `integration` and `benchmark` are declared in `pyproject.toml`. Performance suite at `tests/performance/` is opt-in via `-m benchmark`.
+- **Coverage gate:** `fail_under = 85` in `pyproject.toml`. CI enforces it. New code expected at ≥90% per CONTRIBUTING.
+- **Lint:** `ruff check .` and `ruff format .` before pushing.
+
+## Two CLIs — do not flip them
+
+Naming is locked (sprint plan Flag, do not re-derive):
+
+| Surface | Entry point | Commands |
+|---|---|---|
+| **User CLI** `rootsign` | `rootsign.sdk.cli:app` | `verify`, `approve`, `approve --list` |
+| **Operator CLI** `rootsign-admin` | `rootsign.cli:app` | `start-db`, `stop-db`, `init`, `status` |
+
+`rootsign approve <id>` is a developer workflow on the user CLI. `rootsign-admin replay-pending` (when it lands) is a privileged schema-level operation on the operator CLI. Decorator is `@rootsign.trace`, never `@providex.trace`. Package is `rootsign`, never `providex`.
+
+## Big-picture architecture
+
+**Hash chain (per-session, tamper-evident).** Each `Action` row carries `prev_action_hash` linking to the previous action in its session. `compute_action_self_hash` in `rootsign/hashing.py` is the **frozen canonical spec** — ADR-001 governs it, and CONTRIBUTING refuses to merge changes without a new ADR. Never re-implement it (the local-verify path got this wrong once and silently broke; see commit 128cec5). `self_hash` deliberately excludes `input_redacted`/`output_redacted` — the chain proves hash integrity, not payload-to-hash binding (an open pre-Phase-2 audit item).
+
+**Ingest path.** SDK constructs an envelope → `IngestClient.handle(envelope)` → `IngestHandler` validates and routes by `event_type` → CRUD writes. `LocalIngestClient` is the in-process v0.1.0 path. `HttpIngestClient` is the Phase 2 hosted-backend path. Failure isolation rule (ADR-002): ingest **never raises into the decorated tool**; failures log at WARNING and the tool returns normally.
+
+**HiTL checkpoint (ADR-007 — locked design).** `require_approval=True` on `@rootsign.trace` inserts an `ACTION_RECORD` with `authorization_status='pending'` and a reserved sequence number at submission time, then waits on `HiTLCheckpoint` (async poll loop). On approval: tool runs. Timeout: status becomes `'timed_out'` (terminal, distinct from `'human_rejected'`) and an Approval row is written with `approver_type='timeout_auto_rejected'`. **APPROVAL_RECORD rows are NOT in the hash chain** — they're a separate entity queried independently. The poll loop opens its own `AsyncSession` per cycle (`session_factory=AsyncSessionLocal`), never the caller's.
+
+**Storage.** PostgreSQL 16 + TimescaleDB 2.x. The `actions` table is a **hypertable partitioned by `timestamp`**, which has hard consequences for any code joining against it (see below).
+
+**Migrations.** Live in `rootsign/_migrations/` so they ship inside the wheel. `rootsign-admin init` resolves the directory via `importlib.resources.files("rootsign") / "_migrations"` and builds `alembic.config.Config` programmatically — no `alembic.ini` lookup, no cwd assumption. Developers running `alembic` directly from repo root work via the root-level `alembic.ini` whose `script_location` points at the same directory.
+
+## Test invariants (binding rules)
+
+These were locked in the Sprint 3/4 plans because each one traces to a specific incident. Audit any new SDK or test code against them.
+
+1. **`_emit_action_record` and `_emit_approval_record` are keyword-only.** No positional args.
+2. **AsyncSession loop binding:**
+   - Tool calls in async tests use `await tool.ainvoke({...})` — never `tool._run(...)` or sync `tool.invoke(...)`.
+   - CLI tests in async use `await asyncio.to_thread(runner.invoke, app, [...])` — never bare `runner.invoke(...)`. Typer's runner does `asyncio.run()` internally and crashes inside an already-running loop.
+3. **`seeded_agent` (commits) for HiTL / CLI / `asyncio.to_thread` tests.** `registered_agent` uses SAVEPOINT rollback — its data is invisible to the poll loop's per-cycle session, the `to_thread` CLI runner, and the timeout recorder.
+4. **HiTL design is locked (ADR-007).** Don't re-derive it in code.
+5. **Hypertable-safe Action lookups.** Single-column `action_id` lookups are forbidden. Two valid two-column forms:
+   - `(action_id, action_timestamp)` — canonical chain-link form (`CRUDApproval.create_with_chain_link`, HiTL CLI / poll-loop paths). Prunes chunks on the partition column.
+   - `(session_id, action_id)` — `CRUDApproval.create_with_action_status_update` (ingest path). `ApprovalRecordPayload` doesn't carry `action_timestamp`; switching would require an envelope-schema bump.
+6. **`tests/integration/test_show_hn_quickstart.py` is the launch gate.** It mirrors the README's LangGraph quickstart end-to-end (register → instrument → verify) and must stay green.
+
+## What's deliberately orphaned
+
+- **`_emit_approval_record`** in `rootsign/sdk/decorator.py` has zero call sites in `rootsign/`. It's a Phase 2 hook for when `HttpIngestClient` lands — the v0.1.0 HiTL CLI writes APPROVAL_RECORD rows directly via `CRUDApproval.create_with_chain_link` (single source of truth). Re-emitting via the IngestClient path would hit the terminal-state guard and warn for no semantic gain. The marker comment above the def points at this; don't delete the helper or its tests.
+
+## Authoritative context
+
+When changing anything in the SDK, HiTL, or hashing paths:
+
+- `docs/adr/ADR-001` — canonical hash spec (frozen)
+- `docs/adr/ADR-002` — ingest failure isolation
+- `docs/adr/ADR-006` — redaction contract
+- `docs/adr/ADR-007` — HiTL checkpoint design
+- `AGENTS_Phase1_Sprint4.md` — sprint plan with naming contract, six binding flags, ADR-007 summary, the launch review checklist. **Gitignored**, so absent from fresh clones; it's a working doc for whoever's driving the sprint.
+- `rootsign_review.md` — pre-launch audit findings. Also gitignored. High-severity items were fixed in commit 128cec5; the remainder is the Pre-Phase-2 backlog (concurrency on approvals, payload→hash binding at verify, HiTL classification edge cases, CLI polish).
+
+## Conventions
+
+- **Commits:** `type(scope): short description` (see CONTRIBUTING). Recent history matches: `fix(packaging):`, `fix(security):`, `feat(sdk):`, `docs:`. Body explains *why*, references file:line, and includes a `Co-Authored-By` trailer when relevant.
+- **Branches:** `feat/`, `fix/`, `test/`, `docs/` prefixes.
+- **Hard "no":** mock-based integration tests (real PG+TimescaleDB only), sync SQLAlchemy outside Alembic, changing `compute_action_self_hash` without a new ADR, silently swallowing ingest failures (must log at WARNING), committing/pushing project or sprint artifacts (see top section).

rootsign-0.1.1/CONTRIBUTING.md

@@ -0,0 +1,82 @@
+# Contributing to RootSign
+
+## Welcome
+
+RootSign is the open-source agent capture layer of the Providex AI Agent Accountability Platform. We welcome contributions of all kinds: bug fixes, documentation improvements, new framework integrations, and test coverage.
+
+## Before you contribute
+
+- **Code of Conduct.** RootSign adopts the [Contributor Covenant v2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/) as its code of conduct. By participating in this project (issues, PRs, discussions, Discord), you agree to uphold its standards. Report unacceptable behavior to `info@getprovidex.com`.
+- Sign the [CLA](CLA.md) (automated — you'll be prompted on your first PR)
+- Check the issue tracker for existing discussion before opening a new issue
+
+## Development setup
+
+```bash
+git clone https://github.com/Providex-AI/rootsign
+cd rootsign
+pip install -e '.[dev]'          # installs dev + test deps
+docker-compose up -d db          # PostgreSQL + TimescaleDB
+rootsign-admin init              # alembic upgrade head
+python -m pytest tests/unit/ -v          # unit tests (no DB needed at runtime — see note)
+python -m pytest tests/integration/ -v   # integration tests (needs DB)
+```
+
+> **Python:** RootSign requires Python 3.11 or 3.12. We do not support 3.10 or below.
+>
+> The package's `requires-python` is `>=3.11,<3.15`, but the `[crewai]` extra currently lacks wheels for 3.13/3.14 so installs of `'.[crewai]'` on those versions fail with `No matching distribution found`. Bump the recommendation only after upstream ships matching wheels.
+>
+> **Always invoke pytest as `python -m pytest`.** If you `brew install`-ed pytest, the system binary will resolve ahead of the venv's pytest on PATH and run under the system Python — which does not see your venv's site-packages and will fail with confusing `ModuleNotFoundError` (typically on `sqlalchemy` first). `python -m pytest` always uses the venv's interpreter.
+>
+> **Note on unit tests:** The session-scoped `_bootstrap_test_db` fixture in `tests/conftest.py` runs alembic against the test DB before any test (including unit tests). Bring `docker-compose up -d db` up first.
+
+## Branch naming
+
+```
+feat/[short-description]         # new feature
+fix/[short-description]          # bug fix
+test/[short-description]         # test additions
+docs/[short-description]         # documentation only
+```
+
+## Commit message format
+
+```
+type(scope): short description
+```
+
+Examples:
+```
+feat(sdk): add CrewAI tool wrapper
+fix(hashing): correct canonical field order
+test(crud): add verify_chain corruption test
+docs(adr): add ADR-004 for retry strategy
+```
+
+## Pull request requirements
+
+- All existing tests must pass: `pytest tests/ -v`
+- New code must have test coverage >= 90%
+- Overall coverage must not drop below 85% (enforced by `fail_under = 85` in `pyproject.toml`)
+- No breaking changes to the canonical hash spec without a new ADR (see [ADR-001](docs/adr/ADR-001-hash-canonical-spec.md))
+- Framework integrations must pass contract tests on all supported framework versions (see CI matrix)
+- Run `ruff check .` and `ruff format .` before pushing
+
+## What we will NOT merge
+
+- Changes to `compute_action_self_hash` canonical spec (see [ADR-001](docs/adr/ADR-001-hash-canonical-spec.md)) without a new ADR approved by the maintainer
+- Synchronous SQLAlchemy in any non-Alembic code
+- Mock-based integration tests (real PostgreSQL + TimescaleDB only — see [the data model rationale](AGENTS.md))
+- Any PR that reduces test coverage below 85% overall
+- Code that swallows ingest failures silently (RootSign's promise is that ingest never raises into the agent, but failures *must* be logged at WARNING level — see [ADR-002](docs/adr/ADR-002-transport-agnostic-client.md))
+
+## Adding a new framework integration
+
+1. Open a `framework_integration` issue first so we can discuss API surface and version targets
+2. Copy the LangGraph integration as a reference (lands in Sprint 2)
+3. Implement contract tests against a minimum of two framework versions (latest stable + previous minor) — see [ADR-003](docs/adr/ADR-003-framework-contract-tests.md)
+4. Update `docs/framework-support.md` (created in Sprint 2)
+
+## Questions?
+
+Open a [GitHub Discussion](https://github.com/Providex-AI/rootsign/discussions). A `#rootsign` channel on the LangChain Discord is coming alongside Sprint 2.

rootsign-0.1.1/CONTRIBUTORS.md

@@ -0,0 +1,11 @@
+# Contributors
+
+Thank you to everyone who has contributed to RootSign.
+
+## Maintainers
+
+- Olasile Abolade ([@oabolade](https://github.com/oabolade)) — Founder, Providex AI
+
+## Contributors
+
+*Your name here (@your-github-handle) — one line description of what you worked on*