sia-hu 0.4.0__tar.gz

sia_hu-0.4.0/.codegraphinclude

@@ -0,0 +1,42 @@
+# .codegraphinclude — ! means EXCLUDE (reverse of gitignore re-inclusion)
+#
+# Admits every sia-hu subsystem so the graph targets all source, tests,
+# config, scripts, tools, and the dependency manifests they reference.
+# Bare files are intentionally NOT listed: a bare positive file makes its
+# parent (the project root) a scan root and silently widens ix coverage.
+# See ../codegraph-ferrari/docs/INDEX_SCOPE.md.
+
+# === SOURCE CODE ===
+src/
+capture-proxy/
+model_headroom/
+scripts/
+tools/
+
+# === EXCLUSIONS (apply within scan roots) ===
+# Build/runtime artifacts
+!__pycache__/**
+!.venv/**
+!.codegraph/**
+!.ix/**
+!node_modules/**
+!target/**
+!build/**
+!dist/**
+
+# Test caches
+!.pytest_cache/**
+!.mypy_cache/**
+!.ruff_cache/**
+!htmlcov/**
+
+# Non-source text
+!*.md
+!*.log
+!*.toml
+!*.yaml
+!*.yml
+
+# VCS / editor
+!.git/**
+!.sniper/**

sia_hu-0.4.0/.github/workflows/ci.yml

@@ -0,0 +1,43 @@
+name: CI
+
+on:
+  push:
+    branches: [main, public-repo]
+  pull_request:
+    branches: [main, public-repo]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: uv sync --extra dev --extra headroom --extra gguf
+      - name: Install rclone
+        run: |
+          curl https://rclone.org/install.sh | sudo bash
+      - name: Configure rclone gdrive remote
+        run: |
+          mkdir -p ~/.config/rclone
+          cat > ~/.config/rclone/rclone.conf << 'EOF'
+          [gdrive]
+          type = local
+          root = /tmp/rclone-gdrive-dummy
+          EOF
+      - name: Lint
+        run: uv run ruff check .
+      - name: Format check
+        run: uv run ruff format --check .
+      - name: Type check
+        run: uv run mypy src/
+      - name: Tests
+        run: uv run pytest -q

sia_hu-0.4.0/.github/workflows/publish.yml

@@ -0,0 +1,33 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/sia-hu
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Build
+        run: uv build
+      - name: Check distribution
+        run: uv run --with twine twine check dist/*
+      - name: Inspect wheel contents
+        run: |
+          uv run python -c "
+            import glob, zipfile
+            whl = glob.glob('dist/*.whl')[0]
+            with zipfile.ZipFile(whl) as z:
+                for name in z.namelist():
+                    print(name)
+          "
+      - name: Publish
+        run: uv publish

sia_hu-0.4.0/.gitignore

@@ -0,0 +1,78 @@
+# === Python ===
+__pycache__/
+*.py[cod]
+*.pyo
+*.egg-info/
+*.so
+*.egg
+dist/
+build/
+
+# === Virtual environments ===
+.venv/
+venv/
+ENV/
+.env
+.env.*
+
+# === Tooling caches ===
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.uv-cache/
+
+# === IDE / OS ===
+.idea/
+.vscode/
+*.swp
+*.swo
+.DS_Store
+Thumbs.db
+
+# === Secrets ===
+*.pem
+*.key
+
+# === Tool artifacts (repo-wide) ===
+.ix/
+.imodent/
+.sniper/
+.githooks/
+
+# === CodeGraph (dev-only) ===
+.codegraph/
+.codegraph/codegraph.db
+.codegraph/codegraph.db-shm
+.codegraph/codegraph.db-wal
+/reasoning.db
+.codegraph/cache/
+.codegraph/community_cache.json
+.codegraph/ct_cache.db
+.codegraph/ct_cache.db-shm
+.codegraph/ct_cache.db-wal
+.codegraph/ct_scan.lock
+.codegraph/knowledge.sled/
+.codegraph/neighborhoods.json
+.codegraph/neighborhoods.json.meta.json
+.codegraph/.lock*
+.codegraph/repo_registry.json
+.codegraph/semantic_summaries.json
+.codegraph/sled_cache.json
+.codegraph/sled_patterns.json
+.codegraph/sled_patterns.json.meta.json
+
+# === Agentic artifacts (alpha — not published) ===
+AGENTS.md
+.annotations/
+.maat/
+.maintenance/
+thoughts.jsonl
+.mcp.json
+.opencode/
+.opencode/agents/*.md
+failed_reason.txt
+
+# === Logs ===
+*.log

sia_hu-0.4.0/.ixd.toml

@@ -0,0 +1,38 @@
+# .ixd.toml — ix daemon / CLI index scope for sia-hu (unified)
+#
+# Canonical flat schema (ix >= 0.14). Coarse scoping only; admission is governed
+# by .codegraphinclude. See ../codegraph-ferrari/docs/INDEX_SCOPE.md.
+#
+# watch_roots lists directories to index (relative to this file's directory);
+# ix discovers the root plus one level deep via Path::starts_with. Roots must
+# stay congruent with the positive roots in .codegraphinclude so the ix search
+# surface never diverges from what codegraph admits.
+
+watch_roots = [
+    "src",
+    "capture-proxy",
+    "model_headroom",
+    "scripts",
+    "tools",
+]
+
+# DIRECTORY NAMES, exact match — not globs, no trailing slashes.
+# lost+found / .git / .ix / .codegraph are hardcoded in ix and need not be
+# listed here. Every other default relied upon must be explicit because an
+# existing file yields an empty list via #[serde(default)].
+exclude_patterns = [
+    "__pycache__",
+    ".venv",
+    ".codegraph",
+    ".ix",
+    "node_modules",
+    "target",
+    "build",
+    "dist",
+    ".pytest_cache",
+    ".mypy_cache",
+    ".ruff_cache",
+    "htmlcov",
+]
+
+debounce_ms = 500

sia_hu-0.4.0/.python-version

@@ -0,0 +1 @@
+3.13

sia_hu-0.4.0/CHANGELOG.md

@@ -0,0 +1,56 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.4.0] - 2026-11-10
+
+### Added
+- `capture-proxy --sync` (one-shot), `--sync-daemon`, `--sync-stop`, `--sync-status` — native off-box capture sync via rclone subprocess; no new runtime Python dependency (pure stdlib), no restored shell scripts. New optional `env` extra (`wrapt>=1.16`) for Kaggle self-healing; not in `[project].dependencies`. Settings flags: `--sync-remote`, `--sync-cmd` (default `copy`), `--sync-min-age` (default `60s`), `--sync-interval` (default `300`), `--sync-dry-run`, `--sync-rclone-opts`, `--sync-rclone-binary`, `--sync-machine-id`, `--sync-pid-file`, `--sync-log-file`.
+- `sia doctor` — read-only workspace preflight; every failure names its fix command; exit 0/1/2 (2 on flag errors).
+- `sia publish` — push current branch and verify the remote ref matches local HEAD; never auto-commits; `--dry-run` / `--allow-dirty`; credential URLs redacted in output.
+
+### Changed
+- Version bumped `0.3.0` → `0.4.0` (`pyproject.toml`).
+- `pytest testpaths` extended to include root `tests/`; `sia` added to coverage `source`.
+
+### Removed
+- `rclone-sync-captures.sh`, `bootstrap-capture.sh`, `bootstrap.sh` shell scripts — replaced by native `capture-proxy --sync*` flags and `sia doctor`/`sia publish` verbs.
+
+## [0.3.0] - 2026-11-10
+
+### Added
+- `--device {auto,cuda,cpu}` on `model-headroom` (default `auto`): accelerator-preferred device selection (cuda → xpu → mps → cpu), resolving through new `src/model_headroom/device.py`. `auto` picks the first available accelerator else CPU; `--device cuda` on a box with no CUDA exits 1 with an informative error, never silently downgrades. The resolved device is recorded in `report.metadata["device"]`.
+- New public module `src/model_headroom/device.py` (`available_accelerators()`, `default_device()`, `resolve_device(requested) -> str | None`) — the single source of truth for device selection, threaded into `run_analysis(..., device=...)` and into the GGUF weight-sampling path.
+- New `tools/engine_probe.py` capability probe: workspace shim importing neither package and no torch; `probe_engines()` returns a JSON manifest of installed/running serving engines with capability set (`chat_completions`, `embeddings`, `rerank`, `routed_experts`, `hidden_states`), measured hardware, and hard limits. Never raises, never starts/stops a server, never binds a port; identifies an engine by its own `/v1/models` metadata.
+- New `env` optional-dependency extra (`wrapt>=1.16`): self-healing on Kaggle-class hosts whose system `sitecustomize.py` imports `wrapt`. Deliberately NOT in `[project].dependencies` — sia-hu never imports wrapt, and a published wheel must not ship a bogus runtime dependency.
+- New "Engine Selection Policy" section separating HARD constraints (routed_experts and hidden-state capture require SGLang; measurement signals cannot be served and need in-process forward passes) from PREFERENCES (llama.cpp for GGUF/low-VRAM/FastMTP, vLLM for dense throughput and `/v1/rerank`).
+
+### Changed
+- NFR-01 rewritten: previously mandated CPU-only weight loading; now mandates accelerator-preferred with CPU fallback. The 21 frozen dataclasses were not touched.
+- `model-headroom-refusal --device` default changed from `cpu` to `auto`: an unflagged refusal run now selects the first available accelerator (cuda → xpu → mps → cpu) instead of silently capturing on CPU; `--device cuda` on a box with no CUDA exits 1, `--device cpu` stays on CPU. `src/model_headroom/refusal/cli.py:158-163`.
+- `recover_direction_from_weight_deltas(deltas, spec, device="cpu")` now runs `torch.linalg.svd` on the resolved device and returns the direction on CPU so the serialized report stays device-independent. `src/model_headroom/refusal/recover.py:34-38,103-119,149`; wired at `src/model_headroom/refusal/cli.py:417`.
+- The SVD failure message now names the device and suggests `--device cpu`: `SVD failed on device {device}: {exc}; retry with --device cpu`. `src/model_headroom/refusal/recover.py:128`.
+
+### Fixed
+- Loader error output now reports the specific cause (file does not exist / JSON malformed / missing required keys with the found keys / tensor is 3-D but must be 2-D / empty-but-valid), the offending path, the flag to use, the expected JSON shape, and where a valid example lives — instead of discarding the cause. New `LoadOutcome` + `*_diagnostic` loader functions in `src/model_headroom/models/loader.py`; existing loaders keep their documented `None`-returning contracts.
+
+## [0.2.0] - 2026-11-06
+
+### Added
+- Unified `sia` CLI dispatcher aliasing `capture-proxy`, `model-headroom`, and `model-headroom-refusal`.
+- Unified single project layout (`src/`, one `pyproject.toml`, one `uv.lock`).
+- MIT license.
+- CI workflows for testing and PyPI publishing.
+
+### Changed
+- Raised `requires-python` to `>=3.12` (numpy 2.5.4 requirement).
+- Bumped all dependencies to latest PyPI versions.
+- Ruff target version `py310` → `py312`.
+
+### Fixed
+- Removed engineering-process artifacts from published tree (AGENTS.md, agent definitions, tickets, session artifacts, dev tooling configs).

sia_hu-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Moe Shawky
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sia_hu-0.4.0/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.5
+Name: sia-hu
+Version: 0.4.0
+Summary: Unified headroom measurement: capture-proxy carrier + model_headroom scoring authority
+Project-URL: Homepage, https://github.com/moeshawky/sia-hu
+Project-URL: Repository, https://github.com/moeshawky/sia-hu
+Project-URL: Issues, https://github.com/moeshawky/sia-hu/issues
+Author: Moe Shawky
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: fastapi>=0.162
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic>=2.14.3
+Requires-Dist: uvicorn>=0.54
+Provides-Extra: dev
+Requires-Dist: mypy>=2.4.1; extra == 'dev'
+Requires-Dist: pre-commit>=4.7; extra == 'dev'
+Requires-Dist: pytest-asyncio>=1.4.1.post1; extra == 'dev'
+Requires-Dist: pytest-cov>=7.1; extra == 'dev'
+Requires-Dist: pytest>=9.2; extra == 'dev'
+Requires-Dist: ruff>=0.17.4; extra == 'dev'
+Provides-Extra: env
+Requires-Dist: wrapt>=1.16; extra == 'env'
+Provides-Extra: gguf
+Requires-Dist: gguf>=0.19; extra == 'gguf'
+Provides-Extra: headroom
+Requires-Dist: accelerate>=1.15; extra == 'headroom'
+Requires-Dist: huggingface-hub>=2.4; extra == 'headroom'
+Requires-Dist: numpy>=2.5.4; extra == 'headroom'
+Requires-Dist: safetensors>=0.8.0; extra == 'headroom'
+Requires-Dist: torch>=2.15; extra == 'headroom'
+Requires-Dist: transformers>=5.22.1; extra == 'headroom'
+Description-Content-Type: text/markdown
+
+# sia-hu — Sia + Hu
+
+**Sia** (sỉꜣ): divine perception, deep insight, interior knowledge — perceiving what
+is hidden inside a closed form BEFORE it is spoken (the pre-verbal activation state,
+latent internal representation). **Hu** (ḥw): the uttered word, spoken output, token
+generation.
+
+A logit lens that reads Sia before it becomes Hu is a 1-to-1 conceptual match:
+
+| Egyptian concept | sia-hu role | Repository | What it does |
+|------------------|-------------|------------|--------------|
+| **Sia** — hidden perception | AUTHORITY — scores | `model_headroom/` | Reads model weights (the hidden form) and computes a headroom score in [0.0, 1.0]. Nine signals inspect latent structure: weight spectra, activation balance, expert routing, gradient ratios. |
+| **Hu** — uttered word | CARRIER — emits | `capture-proxy/` | Runs an OpenAI-compatible proxy that logs every request/response before forwarding. Emitted JSONL records, sidecar `headroom.json`, and `weight_pairs.json` are the uttered output — token generation made observable. |
+| The bridge | CLI | `sia` | `sia <subcommand>` forwards to the corresponding existing CLI. Neither scores nor emits itself — it bridges Sia and Hu. |
+
+**Contract (never inverted):**
+- Authority scores (`model_headroom`); carrier never scores (`capture-proxy`).
+- Proxy never scores; authority never proxies.
+- Proxy → authority: emits `{capture_id}.headroom.json` +
+  `{capture_id}-weight_pairs.json` in the loader format the authority consumes.
+- Authority → proxy: defines the 2-D pair contract and signal semantics; the proxy
+  never invents a signal meaning.
+- Agreement between the authority and carrier implementations is the cross-check — one
+  voice is an echo.
+
+See `docs/architecture/sia-hu-identity.md` for the full cosmology, and
+`docs/index.md` for the unified documentation tree.
+
+---
+
+## One project, two packages
+
+| Package | Role | Rule |
+|---------|------|------|
+| `src/model_headroom/` | **Authority** — scores training headroom (reads Sia) | Never proxies |
+| `src/capture_proxy/` | **Carrier** — emits sidecar capture (emits Hu) | Never scores |
+
+Both are **tracked packages inside this single repo** — not submodules, not gitignored, not separate remotes. One clone carries the whole workspace: single `pyproject.toml`, single `uv.lock`, single ruff/mypy/pytest config, installed editable from the repo root, exposing `capture-proxy`, `model-headroom`, `model-headroom-refusal`, and `sia`.
+
+`model_headroom` is the sole scoring authority; `capture-proxy` emits artifacts in the format the authority consumes. Agreement between the two is the cross-check.
+
+---
+
+## The unified `sia` CLI
+
+`sia <subcommand> <args>` forwards to the corresponding existing CLI's `main()`:
+
+| `sia` subcommand | Forwards to | Role |
+|------------------|-------------|------|
+| `sia capture-proxy` | `capture-proxy` | Carrier — emits Hu |
+| `sia model-headroom` | `model-headroom` | Authority — scores Sia |
+| `sia model-headroom-refusal` | `model-headroom-refusal` | Refusal analysis |
+
+Each `main()` returns an `int` and only calls `sys.exit()` inside its
+`if __name__ == "__main__"` guard. Exit codes propagate. `sia` adds no flags,
+no behavior, no new subcommands beyond the three it aliases.
+
+See `docs/guides/sia-cli.md` and `docs/reference/cli-flags.md`.
+
+---
+
+## Quick start
+
+```bash
+pip install -e .                # carrier package only
+pip install -e ".[headroom]"     # + torch / numpy / safetensors (scoring)
+pip install -e ".[dev]"         # + pytest / mypy / ruff
+```
+
+Verify: `ruff check . && ruff format --check . && mypy src/ && pytest`
+
+Full install, bootstrap, and verification steps: `docs/guides/quickstart.md`.
+Verify chain details: `docs/operations/verify-chain.md`.
+
+---
+
+## Repository layout
+
+```
+sia-hu/
+  README.md            → this file
+  AGENTS.md            → agent/operator gate (gitignored, on disk)
+  PROJECT-ROADMAP.md   → unified `sia` CLI plan, phases 1-2
+  pyproject.toml       → single project (sia-hu); one lockfile
+  src/                 → source packages (capture_proxy, model_headroom, sia)
+  capture-proxy/       → carrier tests, config, scripts (docs moved to docs/)
+  model_headroom/      → authority tests (docs moved to docs/)
+  docs/                → unified documentation tree
+  tools/               → repo tools
+```
+
+## Documentation
+
+Unified docs live in `docs/` at the repo root. Start with
+[`docs/index.md`](docs/index.md).
+
+| Section | Purpose |
+|---------|---------|
+| `docs/architecture/` | Sia/Hu identity, authority/carrier division, bidirectional contract |
+| `docs/concepts/` | Headroom signals (R-01–R-09), provenance, frozen contracts |
+| `docs/guides/` | Quickstart, `sia` CLI, carrier guide, authority guide |
+| `docs/operations/` | Verify chain, dev commands, environment |
+| `docs/reference/` | CLI flags, env vars, file layout |
+| `docs/capture-proxy/` | Carrier README, roadmap, design notes (moved from `capture-proxy/`) |
+| `docs/model-headroom/` | Authority README, roadmap, test protocol (moved from `model_headroom/`) |
+
+Authority and carrier roadmaps, test protocol, and package READMEs now live
+under `docs/` (see `docs/reference/file-layout.md`).
+
+Key docs:
+- `docs/architecture/sia-hu-identity.md` — cosmology in detail
+- `docs/architecture/authority-carrier.md` — who scores, who emits
+- `docs/architecture/contract.md` — bidirectional contract, 2-D pair contract
+- `docs/concepts/headroom-signals.md` — R-01 through R-09 signal reference
+- `docs/guides/quickstart.md` — install, bootstrap, verify
+- `docs/guides/capture-proxy.md` — carrier usage
+- `docs/guides/model-headroom.md` — authority usage
+- `docs/operations/verify-chain.md` — ruff → format → mypy → pytest
+- `docs/reference/cli-flags.md` — all CLI flags
+- `docs/reference/env-vars.md` — all env vars
+
+---
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).

sia_hu-0.4.0/PROJECT-ROADMAP.md

@@ -0,0 +1,85 @@
+# PROJECT-ROADMAP.md — sia-hu unified CLI
+
+## Intent Statement
+
+Provide one operator surface, `sia`, over the three package CLIs — `capture-proxy`, `model-headroom`, and `model-headroom-refusal` — and over the workspace operations that were previously carried by shell scripts.
+
+The aliasing contract is unchanged: `sia <subcommand> <args>` forwards to the matching existing CLI's `main()` and propagates its exit code. Two deliberate expansions are authorized by the operator (2026-11-10), because the shell scripts that carried these capabilities were removed on purpose and must not be restored:
+
+- **`capture-proxy --sync`** — native off-box capture sync, replacing `rclone-sync-captures.sh` and the sync step of `bootstrap-capture.sh`. Every other capability of `bootstrap-capture.sh` already exists as a native flag (`--ensure-config`, `--daemon`, `--status`, `--stop`, `--print-effective-config`).
+- **`sia doctor` and verified publish** — native workspace preflight and push verification, replacing `bootstrap.sh`. The load-bearing capability there is refusing to trust `git push` exit 0: the remote ref is compared to local HEAD.
+
+`capture-proxy` is therefore no longer byte-for-byte unchanged. That is a recorded decision, not drift: the removed scripts are the specification, and the native flags are their replacement.
+
+## Current State (Verified from codebase survey)
+
+- **Single root project**: `sia-hu` 0.3.0, one `pyproject.toml`, one `uv.lock`, one ruff/mypy/pytest config at the repo root
+- **Three console scripts** already defined in `[project.scripts]`:
+  - `capture-proxy = "capture_proxy.__main__:main"`
+  - `model-headroom = "model_headroom.cli:main"`
+  - `model-headroom-refusal = "model_headroom.refusal.cli:main"`
+- **Each `main()`** returns an `int` and only calls `sys.exit()` inside its `if __name__ == "__main__"` guard — safe to import and call directly from a new dispatcher
+- **Packages live under `src/`**: `src/capture_proxy/`, `src/model_headroom/`, `src/sia/`
+- **The `sia` dispatcher exists** (Phase 1) and currently adds no verbs of its own
+- **Verify chain**: `ruff check . && ruff format --check . && mypy src/ && pytest` (run from repo root)
+
+## Gap
+
+Measured 2026-11-10 against `master-archive` (the branch that still holds the scripts) and against the current `src/` tree:
+
+- `bootstrap-capture.sh` (115 lines): its config, daemon, status, and effective-config steps are native; its sync step is not.
+- `rclone-sync-captures.sh` (191 lines): **no native equivalent anywhere in `src/`**. `rg rclone` hits only `AGENTS.md`.
+- `bootstrap.sh` (330 lines): **no native equivalent**. Its unique load-bearing piece is push verification.
+- `sia` has **no tests**: `testpaths` covers only `capture-proxy/tests` and `model_headroom/tests`, and no test file references `sia`.
+
+## Planned Phases
+
+### Phase 1: Add `sia` CLI package (COMPLETE)
+- **Goal**: Create `src/sia/` package with `cli.py` that uses argparse subparsers to dispatch `capture-proxy`, `model-headroom`, `model-headroom-refusal` to the existing `main()` functions
+- **Success criterion**: `sia capture-proxy --help`, `sia model-headroom --help`, `sia model-headroom-refusal --help` each show the corresponding subcommand's help; `sia --help` lists all three subcommands; exit codes propagate
+- **Scope**: New files only — `src/sia/__init__.py`, `src/sia/cli.py`. Edit `pyproject.toml` to add `sia` console script and `src/sia` to wheel packages. Zero changes to `src/capture_proxy/` or `src/model_headroom/`.
+
+### Phase 2: Verify (COMPLETE)
+- **Goal**: Run the full verify chain and confirm both package test suites still pass
+- **Success criterion**: `ruff check . && ruff format --check . && mypy src/ && pytest` all exit 0; existing `capture-proxy`, `model-headroom`, `model-headroom-refusal` console scripts still work unchanged
+
+### Phase 3: Native `capture-proxy --sync` (AUTHORIZED — not started)
+- **Goal**: Replace `rclone-sync-captures.sh` with a native sync mode, so off-box capture sync is a property of the installed binary rather than of a shell file that no longer exists
+- **Success criterion**: one-shot sync and daemon loop both work against an rclone remote; re-running the daemon start is idempotent; a missing rclone produces an instructive error naming the flag, the expected value, and a valid example
+- **Constraints**: `copy` is the default; `sync` (destructive mirror) is refused unless the instance id is explicit; instance keying preserves `CAPTURE_MACHINE_ID` > hostname > `/etc/machine-id`; `--min-age` skips files still being written; sync never touches the response path; no new Python dependency
+- **Scope**: new `src/capture_proxy/sync.py`, `__main__.py` wiring, `_CONFIG_KEYS` additions, tests under `capture-proxy/tests/`
+
+### Phase 4: `sia doctor` + verified publish (AUTHORIZED — not started)
+- **Goal**: Replace `bootstrap.sh` with native workspace verbs: a read-only preflight, and a publish that refuses to trust `git push` exit 0
+- **Success criterion**: `sia doctor` changes nothing and reports every failed check with the command that fixes it; `sia publish` pushes the current branch and fails loudly when the remote ref does not match local HEAD
+- **Constraints**: doctor is read-only; publish never auto-commits; a dirty tree is refused unless explicitly overridden; credential-bearing URLs are redacted in every message; `sia` keeps lazy imports so `sia --help` pulls no heavy dependency
+- **Scope**: `src/sia/` native verbs, tests (new `tests/` path or an explicit `testpaths` addition), docs
+
+## Scope-Creep Defenses
+
+- IN scope (authorized 2026-11-10): `capture-proxy --sync`; `sia doctor`; `sia` verified publish; the tests and docs that cover them
+- OUT of scope: restoring any removed shell script; changing the existing behavior of the three aliased CLIs; adding scoring to the carrier; any sync backend other than rclone; auto-commit in publish
+- The earlier "no new flags, no new subcommands" rule is **superseded only for the two items above**. Any further expansion needs a new explicit operator request recorded in this file first
+
+## Controlled-Evolution Path
+
+- `sia` remains an aliasing layer for the three package CLIs, plus the two native workspace verbs recorded in Phase 4
+- `capture-proxy` gains `--sync` only; no other behavior changes
+- A new subcommand or flag requires an explicit operator request recorded in this file before implementation
+
+## Fringe Modules (working, not tested in core verify chain)
+
+- `model-headroom-refusal` (refusal-direction extraction) is implemented and smoke-tested
+  (Qwen3-0.6b: direction_status=computed, cohen_d=4.36, layer model.layers.16).
+  It is a fringe module: not part of the core verify chain, not client-perspective tested,
+  and parked while higher-priority work (release hygiene, carrier/authority contract) proceeds.
+  Revisit only on explicit operator request.
+
+## Drift Checkpoints
+
+- After implementation: re-read intent — confirm no removed shell script was restored, and no scoring entered the carrier
+- Before delivery: confirm all three existing console scripts still work unchanged for their existing flags
+- Verify chain must pass in order: ruff → format → mypy → pytest
+
+---
+*Living document — update at each phase transition.*