ariadex 0.1.0__tar.gz

ariadex-0.1.0/CHANGELOG.md

@@ -0,0 +1,80 @@
+# Changelog
+
+All notable changes to this project are documented here. Versioning is
+informative while the project is pre-release (`0.x`); the packaged version
+lives in exactly one place: `src/ariadex/__init__.py` (`__version__`), and
+`pyproject.toml` reads it dynamically.
+
+## [0.1.0] - 2026-09-12
+
+### Added
+
+- PEP 517/518 packaging (`pyproject.toml`, setuptools src-layout) with
+  `ariadex` console entry point (`ariadex.cli:main`).
+- Declared runtime: Python `>=3.11`, `PyYAML>=6`. No other runtime
+  dependencies.
+- `ariadex --version` reporting the single-source package version.
+- `LICENSE` (MIT), `SECURITY.md`, and pip/pipx/source installation docs.
+- sdist/wheel build validated by installing the wheel into a clean
+  environment and running `ariadex --help` and `ariadex init`.
+
+### Scope reaffirmed
+
+- tmux and Coding CLIs (`opencode`/`codex`) remain external host
+  prerequisites. Ariadex never bundles them and never calls a provider LLM
+  API itself.
+
+## [Unreleased MVP history]
+
+- `project-foundation-and-cli`, `agent-adapters-and-tmux-driver`,
+  `state-driven-runner-and-handoff`,
+  `verification-logging-and-observability`, `human-control-and-resync`,
+  `tmux-auto-install`, `live-runtime-evidence` (see `HANDOFF.md` and
+  `openspec/specs/`).
+
+## [Unreleased post-MVP foundations]
+
+- `packaging-and-distribution`, `ci-quality-security-gates`,
+  `human-supervision-ergonomics`, `single-runner-concurrency-and-recovery`,
+  `log-data-governance`, `spec-dependency-and-execution-governance`,
+  `metrics-export-and-notifications` (see `HANDOFF.md` and
+  `openspec/specs/`). Notable surface: `doctor`, `preview`, `queue`,
+  `history`, `resolve`/`defer`/`reopen`/`reprioritize`, `recover`,
+  `prune-logs`, `export-logs`, `events`, `export-events`, per-change
+   `depends_on` ordering, single-scheduler lease with crash recovery,
+   telemetry retention/redaction, and opt-in redacted notifications.
+
+## [Unreleased audit remediation]
+
+- `active-spec-discovery-and-archive-isolation`: archived changes are
+  never scheduled as active work.
+- `bounded-run-completion-and-cycle-limit`: cycle-limit exhaustion is an
+  explicit incomplete outcome, never success.
+- `takeover-cancellation-and-scheduler-coordination`: takeover and pause
+  cancel in-flight scheduling without new provider input.
+- `canonical-spec-and-doc-governance`: complete canonical purposes,
+  reconciled current/historical docs, and a consistency test.
+- `real-provider-live-validation`: isolated real OpenCode/Codex lifecycle
+  evidence (startup, probe, interrupt, reset, termination, restart).
+- `repository-identity-security-and-release-readiness`: canonical
+  repository `https://github.com/lileililiwen/ariadex`, issues-based
+  security contact, and a fail-closed release dry run
+  (`python -m ariadex.release --tag ...`).
+
+## Release guidance
+
+1. Bump `__version__` in `src/ariadex/__init__.py` only.
+2. Add a `CHANGELOG.md` entry under a new version heading.
+3. Build: `python3 -m build` (produces `dist/ariadex-<version>.tar.gz`
+   and `dist/ariadex-<version>-py3-none-any.whl`).
+4. Verify in a clean virtual environment:
+   `pip install dist/ariadex-<version>-py3-none-any.whl`,
+   then `ariadex --help` and `ariadex init` in a scratch directory.
+5. Tag the release commit (`git tag ariadex-v<version>`).
+6. Dry run (publishes nothing, must pass):
+   `python -m ariadex.release --tag ariadex-v<version>` checks the
+   canonical `origin` remote, package identity URLs, tag/version
+   alignment, artifacts, and the security-reporting route. Pushing the
+   tag runs the release workflow, which re-verifies every gate and then
+   publishes to PyPI via scoped trusted publishing followed by a
+   clean-index install check (`--version`, `init`, `status`).

ariadex-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ariadex contributors
+
+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.

ariadex-0.1.0/MANIFEST.in

@@ -0,0 +1,2 @@
+include LICENSE CHANGELOG.md SECURITY.md README.md pyproject.toml
+global-exclude __pycache__ *.py[cod] *.egg-info

ariadex-0.1.0/PKG-INFO

@@ -0,0 +1,262 @@
+Metadata-Version: 2.4
+Name: ariadex
+Version: 0.1.0
+Summary: Human-supervised runtime for long-running AI coding workflows
+Author: Ariadex contributors
+License: MIT
+Project-URL: Homepage, https://github.com/lileililiwen/ariadex
+Project-URL: Security, https://github.com/lileililiwen/ariadex/blob/main/SECURITY.md
+Project-URL: Changelog, https://github.com/lileililiwen/ariadex/blob/main/CHANGELOG.md
+Keywords: ai,coding,orchestration,tmux
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6
+Provides-Extra: dev
+Requires-Dist: build==1.6.1; extra == "dev"
+Requires-Dist: coverage==7.16.0; extra == "dev"
+Requires-Dist: mypy==2.3.1; extra == "dev"
+Requires-Dist: pip-audit==2.10.1; extra == "dev"
+Requires-Dist: ruff==0.16.7; extra == "dev"
+Requires-Dist: types-PyYAML==6.0.12.20260906; extra == "dev"
+Dynamic: license-file
+
+# Ariadex
+
+Human-supervised runtime for long-running AI coding workflows.
+
+Ariadex keeps Coding CLI work moving across fresh contexts without losing unfinished work. It orchestrates OpenCode and Codex through tmux, with persistent handoffs, verification commands, and explicit human control.
+
+## Status
+
+MVP, all eight post-MVP changes, and all six audit remediation fixes
+are implemented, tested, archived, and committed: project foundation
+and CLI, agent adapters and tmux driver, state-driven runner and
+handoff, verification/logging/observability, human control and resync,
+unattended tmux installation, live runtime evidence, packaging and
+distribution, CI/quality/security gates, human supervision ergonomics,
+single-runner concurrency and recovery, log data governance, spec
+dependency and execution governance, metrics export and notifications,
+active-spec discovery and archive isolation, bounded run completion and
+cycle limit, takeover cancellation and scheduler coordination,
+canonical spec and doc governance, real-provider live validation, and
+ repository identity and release readiness (505 tests, stdlib only). Three
+ follow-up planning changes are active; see [ROADMAP.md](ROADMAP.md) and
+[HANDOFF.md](HANDOFF.md).
+
+## Requirements
+
+- Python 3.11+ and PyYAML (`pip install pyyaml`)
+- A Coding CLI: `opencode` or `codex` on PATH
+- tmux: installed automatically on first `run`/`attach` via the system
+  package manager (apt-get, dnf, yum, pacman, zypper, apk, or brew),
+  using non-interactive `sudo` only when needed. If your host cannot
+  install packages, install tmux yourself or pass `--no-auto-install`
+  to keep the stop-before-work error.
+
+No IDE plugins, LLM API keys, or daemons are required. Ariadex drives the
+Coding CLIs you already use; it never calls a provider LLM API itself.
+
+## Installation
+
+Prerequisites (never bundled, never silently downloaded as packages):
+
+- Python 3.11+ and PyYAML (installed automatically as a dependency)
+- A Coding CLI: `opencode` or `codex` on PATH
+- tmux: installed automatically on first `run`/`attach` via the system
+  package manager, or install it yourself (see Requirements above).
+  Pass `--no-auto-install` to keep the stop-before-work error.
+
+From PyPI with pipx (recommended for CLI use):
+
+```bash
+pipx install ariadex
+ariadex --help
+```
+
+From PyPI with pip:
+
+```bash
+pip install ariadex
+ariadex --help
+```
+
+From a source checkout (no install; uses `./ariadex` wrapper):
+
+```bash
+git clone https://github.com/lileililiwen/ariadex.git && cd ariadex
+./ariadex --help
+```
+
+Verify any installation in a scratch directory:
+
+```bash
+ariadex --version
+mkdir /tmp/ariadex-smoke && cd /tmp/ariadex-smoke
+ariadex init
+```
+
+See [CHANGELOG.md](CHANGELOG.md) for release notes and
+[SECURITY.md](SECURITY.md) for the security contact.
+
+## Quickstart
+
+```bash
+git clone https://github.com/lileililiwen/ariadex.git && cd ariadex
+./ariadex init          # create .ariadex/ defaults, never overwrites
+./ariadex auto          # resync from handoff+git+specs, enter AUTO, schedule
+./ariadex status        # mode, agent, spec, session, unresolved, tests, next
+./ariadex attach        # watch the live Coding CLI in tmux
+```
+
+A typical session:
+
+```bash
+./ariadex run           # execute the next durable action (requires AUTO)
+./ariadex takeover      # stop automatic input, keep observing (MANUAL)
+# ... edit code yourself, in tmux or your editor ...
+./ariadex auto          # resync your edits, verify, resume scheduling
+./ariadex pause         # stop new scheduling, leave the CLI running
+./ariadex resume        # leave PAUSE, back to manual control
+```
+
+## How it works
+
+```text
+Spec -> AI Session -> Handoff -> Fresh Session -> Next Spec
+```
+
+Conversation is temporary state. The repository, specs, and handoff are
+durable state:
+
+- `.ariadex/config.yaml` — agent provider, terminal driver, context
+  strategy, reset mode, spec directory, handoff path, verification
+  commands, retry limit, blocker policy.
+- `.ariadex/handoff.md` — current spec, completed work, unresolved issues
+  (`OPEN`/`RESOLVED`/`DEFERRED`/`BLOCKED`), next action, next spec.
+- `.ariadex/state.json` — mode (`AUTO`/`MANUAL`/`PAUSE`), session,
+  unresolved count.
+- `.ariadex/runs/` and `.ariadex/metrics.jsonl` — per-cycle logs and
+  metrics. Unavailable token usage is recorded as `usage: unavailable`,
+  never estimated.
+- `.ariadex/events.jsonl` — versioned attention events (blocker,
+  verification failure, stale session, verified completion) plus
+  aggregate summaries via `ariadex events` and snapshots via
+  `ariadex export-events`. Notifications are opt-in, redacted,
+  deduplicated, and rate-limited; delivery failure is recorded locally
+  and never changes scheduling.
+
+Modes define input ownership: in `AUTO` Ariadex may schedule and send
+input; in `MANUAL` it only observes and logs; in `PAUSE` it starts no new
+scheduling. A spec advances only when every configured verification
+command exits zero; failures schedule bounded retries, then persist as
+unresolved or blocked work. Nothing is ever silently discarded.
+
+## Commands
+
+| Command            | Effect                                                        |
+| ------------------ | ------------------------------------------------------------- |
+| `init`             | Create `.ariadex/` defaults without overwriting existing files |
+| `run [--yes] [--preview]` | Execute the next action from durable state (needs `AUTO`) |
+| `auto [--yes] [--preview]` | Resync, enter `AUTO`, and resume scheduling             |
+| `attach`           | Attach your terminal to the live tmux Coding CLI session       |
+| `status [--json]`  | Show mode, agent, spec, session, context, elapsed, tests, next |
+| `doctor [--json]`  | Preflight config, provider, tmux, specs, verification, lock    |
+| `preview [--json]` | Show the exact next action and gate; sends no input            |
+| `queue [--status] [--json]` | List unresolved items and history counts            |
+| `history <id> [--json]` | Show an item and its transitions                       |
+| `resolve <id>`     | Mark an item RESOLVED (keeps history)                          |
+| `defer <id> --to --reason` | Mark an item DEFERRED with target and reason         |
+| `reopen <id>`      | Return an item to OPEN (keeps history)                         |
+| `reprioritize <id> --priority` | Change an item priority (keeps history)          |
+| `recover [--json]` | Reconcile state, handoff, lock, and tmux after interruption    |
+| `prune-logs [--yes] [--json]` | Enforce retention/size bounds on telemetry       |
+| `export-logs --out [--json]` | Copy telemetry (`runs/` + `metrics.jsonl`)      |
+| `events [--limit] [--json]` | Show aggregate summary and recent attention events |
+| `export-events --out [--json]` | Write the versioned export snapshot to a file  |
+| `evidence [--gate]`| Run opt-in live runtime evidence (passed/skipped/blocked)      |
+| `pause`            | Enter `PAUSE`; the CLI session keeps running                   |
+| `resume`           | Leave `PAUSE` (valid only from `PAUSE`)                        |
+| `takeover`         | Enter `MANUAL`; automatic input stops, logs continue           |
+| `--no-auto-install`| Never install tmux automatically; stop if it is missing        |
+
+## Configuration
+
+Edit `.ariadex/config.yaml` after `init`. Key settings:
+
+```yaml
+agent_provider: opencode      # opencode | codex
+terminal_driver: tmux          # tmux (MVP driver)
+context_strategy: per-spec    # per-spec | per-task | token-threshold | manual | never
+reset_mode: auto              # soft | hard | auto (fresh-session strength)
+verification_commands: []     # shell commands that gate completion
+retry_limit: 2                # bounded verification retries
+blocker_policy: stop-on-blocker  # stop-on-blocker | record-and-continue
+log_retention_days: 30        # telemetry age bound in days (0 keeps everything)
+log_max_bytes: 10485760       # run-log size cap in bytes
+metrics_max_bytes: 5242880    # metrics file cap in bytes (0 disables that cap)
+notifications_enabled: false  # opt-in attention signals (blocker, failure, stale, done)
+notification_command: []      # argv receiving the redacted payload JSON on stdin
+notification_webhook: ""      # http(s) URL receiving the payload, or empty
+notification_rate_limit: 5    # max deliveries per attention key per window
+notification_window_seconds: 3600  # deduplication/rate-limit window
+```
+
+Add your test/build commands to `verification_commands`; the runner
+executes them in order after adapter work and advances only on full pass.
+
+Order specs with optional per-change metadata
+(`openspec/changes/<name>/.openspec.yaml`):
+
+```yaml
+depends_on: [predecessor-change]  # must be verified complete first
+```
+
+The runner validates dependencies, rejects cycles, selects only eligible
+specs, and preserves missing/cyclic/blocked reasons as unresolved work
+instead of silently substituting another spec.
+
+## Development
+
+```bash
+pip install -e ".[dev]"                              # pinned QA toolchain
+python -m unittest discover -s tests                 # 505 tests, stdlib only
+openspec validate --changes --strict --no-interactive
+ruff check src tests
+ruff format --check src tests
+mypy src/ariadex
+coverage run -m unittest discover -s tests && coverage report  # gate: 82%
+pip-audit --desc=on .
+python -m build                                      # sdist + wheel in dist/
+```
+
+Every CI command above runs locally with the pinned `dev` extra. The
+coverage threshold is the measured baseline: raise it, never lower it.
+Bandit/pylint-style rules are intentionally out of the ruff set (they
+demand behavior-affecting changes; deferred to a hardening pass).
+Releases additionally require `ariadex evidence --gate` (no skips
+allowed) via the tag-triggered release workflow.
+
+See [AGENTS.md](AGENTS.md) for the OpenSpec delivery workflow (one change
+at a time, two-commit handoff) and [HANDOFF.md](HANDOFF.md) for current
+runtime state and verification evidence.
+
+## Scope boundary
+
+Ariadex is an orchestration and lifecycle layer. It does not become an IDE,
+edit code itself, call provider LLM APIs, or reimplement OpenCode, Codex,
+Claude Code, or other Coding CLIs. Still deferred: native PTY driver,
+additional providers, token and cost statistics, advanced retry strategies
+and idle detection, and remote monitoring beyond the provider-neutral
+export boundary. Shipped within the boundary: spec dependency governance,
+single-scheduler crash recovery, log retention/redaction/export, and
+versioned metrics with opt-in notifications.

ariadex-0.1.0/README.md

@@ -0,0 +1,230 @@
+# Ariadex
+
+Human-supervised runtime for long-running AI coding workflows.
+
+Ariadex keeps Coding CLI work moving across fresh contexts without losing unfinished work. It orchestrates OpenCode and Codex through tmux, with persistent handoffs, verification commands, and explicit human control.
+
+## Status
+
+MVP, all eight post-MVP changes, and all six audit remediation fixes
+are implemented, tested, archived, and committed: project foundation
+and CLI, agent adapters and tmux driver, state-driven runner and
+handoff, verification/logging/observability, human control and resync,
+unattended tmux installation, live runtime evidence, packaging and
+distribution, CI/quality/security gates, human supervision ergonomics,
+single-runner concurrency and recovery, log data governance, spec
+dependency and execution governance, metrics export and notifications,
+active-spec discovery and archive isolation, bounded run completion and
+cycle limit, takeover cancellation and scheduler coordination,
+canonical spec and doc governance, real-provider live validation, and
+ repository identity and release readiness (505 tests, stdlib only). Three
+ follow-up planning changes are active; see [ROADMAP.md](ROADMAP.md) and
+[HANDOFF.md](HANDOFF.md).
+
+## Requirements
+
+- Python 3.11+ and PyYAML (`pip install pyyaml`)
+- A Coding CLI: `opencode` or `codex` on PATH
+- tmux: installed automatically on first `run`/`attach` via the system
+  package manager (apt-get, dnf, yum, pacman, zypper, apk, or brew),
+  using non-interactive `sudo` only when needed. If your host cannot
+  install packages, install tmux yourself or pass `--no-auto-install`
+  to keep the stop-before-work error.
+
+No IDE plugins, LLM API keys, or daemons are required. Ariadex drives the
+Coding CLIs you already use; it never calls a provider LLM API itself.
+
+## Installation
+
+Prerequisites (never bundled, never silently downloaded as packages):
+
+- Python 3.11+ and PyYAML (installed automatically as a dependency)
+- A Coding CLI: `opencode` or `codex` on PATH
+- tmux: installed automatically on first `run`/`attach` via the system
+  package manager, or install it yourself (see Requirements above).
+  Pass `--no-auto-install` to keep the stop-before-work error.
+
+From PyPI with pipx (recommended for CLI use):
+
+```bash
+pipx install ariadex
+ariadex --help
+```
+
+From PyPI with pip:
+
+```bash
+pip install ariadex
+ariadex --help
+```
+
+From a source checkout (no install; uses `./ariadex` wrapper):
+
+```bash
+git clone https://github.com/lileililiwen/ariadex.git && cd ariadex
+./ariadex --help
+```
+
+Verify any installation in a scratch directory:
+
+```bash
+ariadex --version
+mkdir /tmp/ariadex-smoke && cd /tmp/ariadex-smoke
+ariadex init
+```
+
+See [CHANGELOG.md](CHANGELOG.md) for release notes and
+[SECURITY.md](SECURITY.md) for the security contact.
+
+## Quickstart
+
+```bash
+git clone https://github.com/lileililiwen/ariadex.git && cd ariadex
+./ariadex init          # create .ariadex/ defaults, never overwrites
+./ariadex auto          # resync from handoff+git+specs, enter AUTO, schedule
+./ariadex status        # mode, agent, spec, session, unresolved, tests, next
+./ariadex attach        # watch the live Coding CLI in tmux
+```
+
+A typical session:
+
+```bash
+./ariadex run           # execute the next durable action (requires AUTO)
+./ariadex takeover      # stop automatic input, keep observing (MANUAL)
+# ... edit code yourself, in tmux or your editor ...
+./ariadex auto          # resync your edits, verify, resume scheduling
+./ariadex pause         # stop new scheduling, leave the CLI running
+./ariadex resume        # leave PAUSE, back to manual control
+```
+
+## How it works
+
+```text
+Spec -> AI Session -> Handoff -> Fresh Session -> Next Spec
+```
+
+Conversation is temporary state. The repository, specs, and handoff are
+durable state:
+
+- `.ariadex/config.yaml` — agent provider, terminal driver, context
+  strategy, reset mode, spec directory, handoff path, verification
+  commands, retry limit, blocker policy.
+- `.ariadex/handoff.md` — current spec, completed work, unresolved issues
+  (`OPEN`/`RESOLVED`/`DEFERRED`/`BLOCKED`), next action, next spec.
+- `.ariadex/state.json` — mode (`AUTO`/`MANUAL`/`PAUSE`), session,
+  unresolved count.
+- `.ariadex/runs/` and `.ariadex/metrics.jsonl` — per-cycle logs and
+  metrics. Unavailable token usage is recorded as `usage: unavailable`,
+  never estimated.
+- `.ariadex/events.jsonl` — versioned attention events (blocker,
+  verification failure, stale session, verified completion) plus
+  aggregate summaries via `ariadex events` and snapshots via
+  `ariadex export-events`. Notifications are opt-in, redacted,
+  deduplicated, and rate-limited; delivery failure is recorded locally
+  and never changes scheduling.
+
+Modes define input ownership: in `AUTO` Ariadex may schedule and send
+input; in `MANUAL` it only observes and logs; in `PAUSE` it starts no new
+scheduling. A spec advances only when every configured verification
+command exits zero; failures schedule bounded retries, then persist as
+unresolved or blocked work. Nothing is ever silently discarded.
+
+## Commands
+
+| Command            | Effect                                                        |
+| ------------------ | ------------------------------------------------------------- |
+| `init`             | Create `.ariadex/` defaults without overwriting existing files |
+| `run [--yes] [--preview]` | Execute the next action from durable state (needs `AUTO`) |
+| `auto [--yes] [--preview]` | Resync, enter `AUTO`, and resume scheduling             |
+| `attach`           | Attach your terminal to the live tmux Coding CLI session       |
+| `status [--json]`  | Show mode, agent, spec, session, context, elapsed, tests, next |
+| `doctor [--json]`  | Preflight config, provider, tmux, specs, verification, lock    |
+| `preview [--json]` | Show the exact next action and gate; sends no input            |
+| `queue [--status] [--json]` | List unresolved items and history counts            |
+| `history <id> [--json]` | Show an item and its transitions                       |
+| `resolve <id>`     | Mark an item RESOLVED (keeps history)                          |
+| `defer <id> --to --reason` | Mark an item DEFERRED with target and reason         |
+| `reopen <id>`      | Return an item to OPEN (keeps history)                         |
+| `reprioritize <id> --priority` | Change an item priority (keeps history)          |
+| `recover [--json]` | Reconcile state, handoff, lock, and tmux after interruption    |
+| `prune-logs [--yes] [--json]` | Enforce retention/size bounds on telemetry       |
+| `export-logs --out [--json]` | Copy telemetry (`runs/` + `metrics.jsonl`)      |
+| `events [--limit] [--json]` | Show aggregate summary and recent attention events |
+| `export-events --out [--json]` | Write the versioned export snapshot to a file  |
+| `evidence [--gate]`| Run opt-in live runtime evidence (passed/skipped/blocked)      |
+| `pause`            | Enter `PAUSE`; the CLI session keeps running                   |
+| `resume`           | Leave `PAUSE` (valid only from `PAUSE`)                        |
+| `takeover`         | Enter `MANUAL`; automatic input stops, logs continue           |
+| `--no-auto-install`| Never install tmux automatically; stop if it is missing        |
+
+## Configuration
+
+Edit `.ariadex/config.yaml` after `init`. Key settings:
+
+```yaml
+agent_provider: opencode      # opencode | codex
+terminal_driver: tmux          # tmux (MVP driver)
+context_strategy: per-spec    # per-spec | per-task | token-threshold | manual | never
+reset_mode: auto              # soft | hard | auto (fresh-session strength)
+verification_commands: []     # shell commands that gate completion
+retry_limit: 2                # bounded verification retries
+blocker_policy: stop-on-blocker  # stop-on-blocker | record-and-continue
+log_retention_days: 30        # telemetry age bound in days (0 keeps everything)
+log_max_bytes: 10485760       # run-log size cap in bytes
+metrics_max_bytes: 5242880    # metrics file cap in bytes (0 disables that cap)
+notifications_enabled: false  # opt-in attention signals (blocker, failure, stale, done)
+notification_command: []      # argv receiving the redacted payload JSON on stdin
+notification_webhook: ""      # http(s) URL receiving the payload, or empty
+notification_rate_limit: 5    # max deliveries per attention key per window
+notification_window_seconds: 3600  # deduplication/rate-limit window
+```
+
+Add your test/build commands to `verification_commands`; the runner
+executes them in order after adapter work and advances only on full pass.
+
+Order specs with optional per-change metadata
+(`openspec/changes/<name>/.openspec.yaml`):
+
+```yaml
+depends_on: [predecessor-change]  # must be verified complete first
+```
+
+The runner validates dependencies, rejects cycles, selects only eligible
+specs, and preserves missing/cyclic/blocked reasons as unresolved work
+instead of silently substituting another spec.
+
+## Development
+
+```bash
+pip install -e ".[dev]"                              # pinned QA toolchain
+python -m unittest discover -s tests                 # 505 tests, stdlib only
+openspec validate --changes --strict --no-interactive
+ruff check src tests
+ruff format --check src tests
+mypy src/ariadex
+coverage run -m unittest discover -s tests && coverage report  # gate: 82%
+pip-audit --desc=on .
+python -m build                                      # sdist + wheel in dist/
+```
+
+Every CI command above runs locally with the pinned `dev` extra. The
+coverage threshold is the measured baseline: raise it, never lower it.
+Bandit/pylint-style rules are intentionally out of the ruff set (they
+demand behavior-affecting changes; deferred to a hardening pass).
+Releases additionally require `ariadex evidence --gate` (no skips
+allowed) via the tag-triggered release workflow.
+
+See [AGENTS.md](AGENTS.md) for the OpenSpec delivery workflow (one change
+at a time, two-commit handoff) and [HANDOFF.md](HANDOFF.md) for current
+runtime state and verification evidence.
+
+## Scope boundary
+
+Ariadex is an orchestration and lifecycle layer. It does not become an IDE,
+edit code itself, call provider LLM APIs, or reimplement OpenCode, Codex,
+Claude Code, or other Coding CLIs. Still deferred: native PTY driver,
+additional providers, token and cost statistics, advanced retry strategies
+and idle detection, and remote monitoring beyond the provider-neutral
+export boundary. Shipped within the boundary: spec dependency governance,
+single-scheduler crash recovery, log retention/redaction/export, and
+versioned metrics with opt-in notifications.

ariadex-0.1.0/SECURITY.md

@@ -0,0 +1,63 @@
+# Security policy
+
+## Supported versions
+
+Only the latest tagged release (currently `0.1.0`) receives security fixes.
+Pre-release `0.x` versions are supported on a best-effort basis.
+
+## Scope notes
+
+- Ariadex orchestrates Coding CLIs you already run; it never calls a
+  provider LLM API itself and stores no API keys.
+- tmux and provider CLIs (`opencode`/`codex`) are external host
+  prerequisites, never bundled artifacts.
+- `.ariadex/runs/` logs and `metrics.jsonl` may contain shell output from
+  your own commands. Review them before sharing.
+
+## Sensitive data handling
+
+- Run logs and metrics are redacted before persistence: OpenAI-style
+  keys, AWS access keys, PEM private-key blocks, `password=`/`token=`
+  assignments, `Bearer` tokens, GitHub (`ghp_`/`gho_`/`github_pat_`) and
+  GitLab (`glpat-`) tokens, Slack tokens, JWTs, and AWS secret fields are
+  replaced with `<redacted>`. Only the redaction count is recorded
+  (`redactions:` in logs, `redactions` in metrics); matched values are
+  never stored.
+- Redaction is heuristic, not a guarantee. Treat logs as sensitive,
+  review `export-logs` output before sharing, and rotate any credential
+  that touched a prompt or shell output.
+- Telemetry files use restrictive permissions where supported (directories
+  `0700`, files `0600`). On Windows, POSIX modes do not apply and `doctor`
+  reports the platform fallback; Windows ACLs govern access instead.
+
+## Retention, backup, and recovery
+
+- Retention is explicit and bounded via `log_retention_days` (default 30,
+  `0` keeps everything), `log_max_bytes` (default 10485760), and
+  `metrics_max_bytes` (default 5242880, `0` disables that cap). Bounds are
+  enforced after every cycle and on demand via `ariadex prune-logs`
+  (confirmation required for interactive use; `--yes` skips the prompt).
+- `prune-logs` and size rotation remove only telemetry under
+  `.ariadex/runs/` and `metrics.jsonl`, oldest first, and report what was
+  removed or retained. Handoff history (`.ariadex/handoff.md`), state,
+  config, and lock files are never touched; deletion never claims work
+  was undone.
+- `ariadex export-logs --out DIR` copies telemetry only into `DIR`,
+  refusing when the payload exceeds `--max-bytes` (default 52428800) so an
+  unbounded export cannot fill the disk. Back up `DIR` with your usual
+  tools; to recover, copy the files back and run `ariadex doctor` and
+  `ariadex recover` to reconcile state before resuming.
+
+## Reporting a vulnerability
+
+Open a GitHub issue at <https://github.com/lileililiwen/ariadex/issues>
+with the `security` label, or contact the maintainers through the same
+tracker. Include:
+
+- affected version (`ariadex --version`)
+- steps to reproduce
+- impact assessment, if known
+
+Do not include secrets, API keys, or private log contents in the report.
+Maintainers will acknowledge receipt, assess, and publish a fix with a
+`CHANGELOG.md` entry.