From 9242e2b8caeef032cedc442dac56655ee3274ce8 Mon Sep 17 00:00:00 2001 From: Zain Dana Harper Date: Mon, 29 Jun 2026 09:47:30 -0700 Subject: [PATCH 1/3] feat: add private-line flagship surface --- .github/workflows/ci.yml | 32 +++++ README.md | 63 ++++++++++ assets/behavior-transform-hero.svg | 50 ++++++++ docs/INTEGRATION_CONTRACT.md | 62 ++++++++++ tests/test_behavior_flagship.py | 43 +++++++ tools/behavior_flagship.py | 184 +++++++++++++++++++++++++++++ 6 files changed, 434 insertions(+) create mode 100644 .github/workflows/ci.yml create mode 100644 README.md create mode 100644 assets/behavior-transform-hero.svg create mode 100644 docs/INTEGRATION_CONTRACT.md create mode 100644 tests/test_behavior_flagship.py create mode 100644 tools/behavior_flagship.py diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..59f4f83 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,32 @@ +name: behavior-transform.io CI + +on: + push: + branches: [main] + pull_request: + branches: [main] + +jobs: + test: + runs-on: ubuntu-latest + timeout-minutes: 10 + + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Setup Python + uses: actions/setup-python@v5 + with: + python-version: "3.11" + + - name: Install test dependencies + run: python -m pip install pytest + + - name: Run tests + run: python -m pytest -q + + - name: Verify flagship envelope + run: | + python -m unittest tests.test_behavior_flagship -v + python tools/behavior_flagship.py doctor --json diff --git a/README.md b/README.md new file mode 100644 index 0000000..e8b39e2 --- /dev/null +++ b/README.md @@ -0,0 +1,63 @@ +# behavior-transform.io + +![behavior-transform.io IO boundary calibration layer](assets/behavior-transform-hero.svg) + +`behavior-transform.io` is the Project Telos private-line IO boundary +calibration layer. It provides local wrappers, hooks, and shell profiles for +read, write, exec, fetch, input, and model-boundary channels. + +Its job is practical: make workstation IO explicit, mode-aware, and receipt +friendly without requiring hosts to ingest raw prompts, private file contents, +secret values, or full model-boundary payloads. + +```bash +python tools/behavior_flagship.py status --json +python tools/behavior_flagship.py doctor --json +python tools/behavior_flagship.py demo --json +``` + +## Flagship Contract + +| Surface | Status | +|---------|--------| +| CLI JSON | `tools/behavior_flagship.py status|doctor|demo --json` | +| Runtime profiles | `ops`, `research`, `academic` | +| Hook surface | Claude Code PreToolUse/PostToolUse hooks in `hooks/` | +| Shell surface | PowerShell, CMD, and sh profile helpers in `profiles/` | +| Interop schemas | `project-telos.flagship-action/v1`, `project-telos.action-receipt/v1`, `project-telos.context-envelope/v1` | +| Privacy boundary | Host receives counts, hashes, verdicts, and redacted refs; local adapters retain raw content | + +## Modes + +| Mode | Profile | Behavior | +|------|---------|----------| +| `ops` | standard | Calibration stack active | +| `research` | native | Source-faithful passthrough | +| `academic` | native | Research alias | + +Switch mode: + +```bash +python tools/io_state.py --set research +python tools/io_state.py --set ops +``` + +## Structure + +```text +tools/ Core modules and CLI wrappers +hooks/ Claude Code hook adapters +profiles/ Shell integration helpers +tests/ Pytest and unittest coverage +docs/ Specs, plans, and integration contracts +``` + +## Verification + +```bash +python -m pytest -q +python tools/behavior_flagship.py doctor --json +``` + +See [docs/INTEGRATION_CONTRACT.md](docs/INTEGRATION_CONTRACT.md) for the IO +boundary contract. diff --git a/assets/behavior-transform-hero.svg b/assets/behavior-transform-hero.svg new file mode 100644 index 0000000..8b53684 --- /dev/null +++ b/assets/behavior-transform-hero.svg @@ -0,0 +1,50 @@ + + behavior-transform.io IO boundary calibration layer + A technical README hero showing behavior-transform.io as an IO membrane between operators, tools, and model-boundary hosts. + + + + + + + + + + + + + + + + + + + + + + + + operator + safe_read / safe_exec / safe_fetch + mode: ops | research | academic + local hashes + redacted refs + + host surface + CLI JSON / hooks / shell profiles + future MCP adapter + MATCH | DRIFT | UNVERIFIABLE + + + + + + + + + + + behavior-transform.io + + Project Telos private-line IO boundary calibration + + diff --git a/docs/INTEGRATION_CONTRACT.md b/docs/INTEGRATION_CONTRACT.md new file mode 100644 index 0000000..d59940c --- /dev/null +++ b/docs/INTEGRATION_CONTRACT.md @@ -0,0 +1,62 @@ +# behavior-transform.io Integration Contract + +`behavior-transform.io` is the private-line IO boundary calibration layer for +Project Telos. It provides local wrappers, hooks, and shell profiles for moving +text through read, write, exec, fetch, input, and model-boundary channels with +explicit mode and provenance handling. + +This repository is not an offensive tooling layer and does not own target +operations. It owns the workstation-local IO membrane around tools that do. + +## Runtime Profiles + +| Profile | Purpose | Transform behavior | +|---------|---------|--------------------| +| `ops` | Default operator mode | Calibration enabled | +| `research` | Source-faithful research mode | Passthrough | +| `academic` | Alias for research review | Passthrough | + +Switching profile is local state only: + +```powershell +python tools/io_state.py --set research +python tools/io_state.py --set ops +``` + +## Host Surfaces + +- CLI JSON envelopes through `tools/behavior_flagship.py` +- Claude Code hooks in `hooks/` +- shell profiles in `profiles/` +- direct safe wrappers in `tools/safe_*.py` +- future MCP adapter surface using the same envelope schema + +## Privacy Boundary + +Hosts may receive: + +- mode and profile names +- wrapper/tool names +- counts +- hashes +- verdicts +- redacted references + +Hosts must not require raw prompts, private file contents, secret values, +credentials, hidden environment values, or full model-boundary payloads. + +## Receipt Shape + +Actions that cross write, exec, fetch, or model-boundary channels should record: + +- `action_intent_id` +- `channel` +- `profile` +- `input_hash` +- `output_hash` or `redacted_output_ref` +- `decision_outcome` +- `verification_verdict` +- `evaluated_at` + +The receipt must be sufficient to replay the boundary decision without exporting +private source content. diff --git a/tests/test_behavior_flagship.py b/tests/test_behavior_flagship.py new file mode 100644 index 0000000..d05465a --- /dev/null +++ b/tests/test_behavior_flagship.py @@ -0,0 +1,43 @@ +import unittest + +from tools.behavior_flagship import ( + SCHEMA, + demo_envelope, + doctor_envelope, + status_envelope, +) + + +class BehaviorFlagshipTests(unittest.TestCase): + def test_status_uses_telos_schema(self) -> None: + envelope = status_envelope() + + self.assertEqual(envelope["schema"], SCHEMA) + self.assertEqual(envelope["tool"], "behavior-transform.io") + self.assertEqual(envelope["status"], "MATCH") + self.assertIn("CLI JSON", envelope["native"]["host_surfaces"]) + self.assertFalse(envelope["native"]["runtime_contract"]["raw_secret_export"]) + + def test_doctor_checks_contract_and_secret_boundary(self) -> None: + envelope = doctor_envelope() + checks = { + item["id"] + for output in envelope["outputs"] + if output["kind"] == "checks" + for item in output["items"] + } + + self.assertIn("required:docs/INTEGRATION_CONTRACT.md", checks) + self.assertIn("raw-secret-boundary", checks) + self.assertEqual(envelope["status"], "MATCH") + + def test_demo_is_local_io_only(self) -> None: + envelope = demo_envelope() + demo = envelope["outputs"][0] + + self.assertEqual(demo["runtime_surface"], "local_io") + self.assertIn("switch back to ops calibration", demo["steps"]) + + +if __name__ == "__main__": + unittest.main() diff --git a/tools/behavior_flagship.py b/tools/behavior_flagship.py new file mode 100644 index 0000000..a012a1f --- /dev/null +++ b/tools/behavior_flagship.py @@ -0,0 +1,184 @@ +#!/usr/bin/env python3 +"""Flagship status, doctor, and demo envelopes for behavior-transform.io.""" + +from __future__ import annotations + +import argparse +import hashlib +import json +import tomllib +from datetime import datetime, timezone +from pathlib import Path +from typing import Any + + +ROOT = Path(__file__).resolve().parents[1] +SCHEMA = "project-telos.flagship-action/v1" + +REQUIRED_FILES = ( + "README.md", + "CLAUDE.md", + "pyproject.toml", + "docs/INTEGRATION_CONTRACT.md", + "assets/behavior-transform-hero.svg", + ".github/workflows/ci.yml", + "tools/io_state.py", + "tools/safe_read.py", + "tools/safe_write.py", + "tools/safe_exec.py", + "tools/safe_fetch.py", + "tools/safe_input.py", + "tools/safe_classify.py", + "hooks/safe-read-redirect.py", + "profiles/warden-profile.ps1", +) + + +def _read_text(rel: str) -> str: + return (ROOT / rel).read_text(encoding="utf-8", errors="replace") + + +def _version() -> str: + data = tomllib.loads(_read_text("pyproject.toml")) + return data.get("project", {}).get("version", "0.0.0") + + +def _sha256_prefix(rel: str) -> str: + return hashlib.sha256((ROOT / rel).read_bytes()).hexdigest()[:16] + + +def _native() -> dict[str, Any]: + return { + "role": "io-boundary-calibration-layer", + "project": "Project Telos private line", + "operator_commands": ["status", "doctor", "demo"], + "host_surfaces": [ + "CLI JSON", + "Claude Code hooks", + "Codex-safe wrapper scripts", + "shell profiles", + "future MCP adapter", + ], + "schemas": [ + SCHEMA, + "project-telos.action-receipt/v1", + "project-telos.context-envelope/v1", + ], + "privacy_boundary": ( + "The host receives mode, profile, tool names, counts, hashes, and " + "verdicts. Raw prompt bodies, private file contents, and secret " + "values stay inside local IO adapters." + ), + "runtime_contract": { + "default_profile": "ops", + "passthrough_profiles": ["research", "academic"], + "receipt_required_for": ["write", "exec", "fetch", "model-boundary"], + "raw_secret_export": False, + }, + } + + +def _envelope(command: str, status: str) -> dict[str, Any]: + return { + "schema": SCHEMA, + "tool": "behavior-transform.io", + "tool_version": _version(), + "command": command, + "status": status, + "generated_at": datetime.now(timezone.utc).isoformat(), + "inputs": [], + "outputs": [], + "receipts": [], + "native": _native(), + "diagnostics": [], + } + + +def status_envelope() -> dict[str, Any]: + envelope = _envelope("status", "MATCH") + envelope["outputs"] = [{ + "kind": "workspace", + "root_sha256_prefix": _sha256_prefix("pyproject.toml"), + "required_files": list(REQUIRED_FILES), + }] + return envelope + + +def _doctor_checks() -> list[dict[str, str]]: + checks: list[dict[str, str]] = [] + for rel in REQUIRED_FILES: + checks.append({ + "id": f"required:{rel}", + "status": "MATCH" if (ROOT / rel).exists() else "DRIFT", + "evidence_ref": rel, + }) + + claude = _read_text("CLAUDE.md") if (ROOT / "CLAUDE.md").exists() else "" + contract = ( + _read_text("docs/INTEGRATION_CONTRACT.md") + if (ROOT / "docs/INTEGRATION_CONTRACT.md").exists() + else "" + ) + checks.extend([ + { + "id": "no-offensive-layer", + "status": "MATCH" if "Add offensive tooling" in claude else "DRIFT", + "evidence_ref": "CLAUDE.md#never", + }, + { + "id": "raw-secret-boundary", + "status": "MATCH" if "secret values" in contract else "DRIFT", + "evidence_ref": "docs/INTEGRATION_CONTRACT.md#privacy-boundary", + }, + ]) + return checks + + +def doctor_envelope() -> dict[str, Any]: + checks = _doctor_checks() + status = "MATCH" if all(check["status"] == "MATCH" for check in checks) else "DRIFT" + envelope = _envelope("doctor", status) + envelope["outputs"] = [{"kind": "checks", "items": checks}] + envelope["diagnostics"] = [check for check in checks if check["status"] != "MATCH"] + return envelope + + +def demo_envelope() -> dict[str, Any]: + envelope = _envelope("demo", "MATCH") + envelope["outputs"] = [{ + "kind": "demo-plan", + "name": "IO boundary mode switch", + "runtime_surface": "local_io", + "steps": [ + "read current IO mode", + "switch to research passthrough", + "switch back to ops calibration", + "run safe wrapper tests", + "emit envelope with mode/profile evidence", + ], + }] + return envelope + + +def main(argv: list[str] | None = None) -> int: + parser = argparse.ArgumentParser(description="behavior-transform.io flagship envelope") + parser.add_argument("command", choices=("status", "doctor", "demo")) + parser.add_argument("--json", action="store_true", help="Emit JSON") + args = parser.parse_args(argv) + + if args.command == "status": + envelope = status_envelope() + elif args.command == "doctor": + envelope = doctor_envelope() + else: + envelope = demo_envelope() + + if args.json: + print(json.dumps(envelope, indent=2, sort_keys=True)) + else: + print(f"behavior-transform.io {args.command}: {envelope['status']}") + return 0 if envelope["status"] == "MATCH" else 1 + + +if __name__ == "__main__": + raise SystemExit(main()) From d9abf356aa7c7a313ed0f0237b24c755905ef00b Mon Sep 17 00:00:00 2001 From: Zain Dana Harper Date: Mon, 29 Jun 2026 10:12:23 -0700 Subject: [PATCH 2/3] docs: add sponsor metadata --- .github/FUNDING.yml | 4 ++++ 1 file changed, 4 insertions(+) create mode 100644 .github/FUNDING.yml diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml new file mode 100644 index 0000000..e48cb64 --- /dev/null +++ b/.github/FUNDING.yml @@ -0,0 +1,4 @@ +github: [HarperZ9] +custom: + - https://harperz9.github.io + - https://harperz9.github.io/field-guide.html From e8e4d7e2138dfaea8f9a4eae9e87155de2ec0473 Mon Sep 17 00:00:00 2001 From: Zain Dana Harper Date: Mon, 29 Jun 2026 10:15:20 -0700 Subject: [PATCH 3/3] ci: update actions for node 24 runners --- .github/workflows/ci.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 59f4f83..c73bd1f 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -13,10 +13,10 @@ jobs: steps: - name: Checkout - uses: actions/checkout@v4 + uses: actions/checkout@v7 - name: Setup Python - uses: actions/setup-python@v5 + uses: actions/setup-python@v6 with: python-version: "3.11"