Metadata-Version: 2.4
Name: specly
Version: 0.1.0
Summary: Spec-Driven Development scaffolding in Python
Author: davidops
License: MIT
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Provides-Extra: strands
Requires-Dist: strands-agents>=1.0.0; extra == "strands"
Provides-Extra: ax

# Specly Python CLI (Local Preview)

Standalone Python distribution for **Specly** — Spec-Driven Development scaffolding without requiring Node.js.

> **Status:** Local development and testing only. This package is **not published** to PyPI or any public registry. The package name and public command identities remain provisional.

## Supported Commands

- `specly init [options]`: Generate SDD files conforming to canonical artifact contract v1.
- `specly doctor`: Read-only readiness check for Python runtime (>=3.10), agent markers, and packaged template fingerprints.
- `specly plan <feature>`: Read-only preview of proposed local file writes and effects.
- `specly verify <feature>`: Read-only verification of local specification files and checklist progress.

*Note: `specly run` and `specly recover` are not supported in the Python CLI and remain available via the Node CLI.*

## Interruption & Overwrite Safety

- Running `init` on existing files checks their SHA-256 against canonical templates.
- Files matching canonical template bytes are reported as already complete and skipped.
- Modified or partial files trigger a warning requiring review; they are never overwritten without explicit `--force`.

## Optional Strands Task Execution Adapter

The optional module `specly_cli.optional.strands_adapter` provides a strictly bounded task-execution boundary using the Strands Agents SDK:

- **Disabled by default:** Default commands (`init`, `doctor`, `plan`, `verify`) never import Strands or inspect ambient credentials.
- **Explicit authorization:** Execution requires an `ExecutionRequest` bound to an affirmative `approval_digest`, explicit provider configuration, and task ID.
- **Strict safety boundary:**
  - Allowed tools are restricted to structured, data-only local operations (`write-file`). Shell, subprocess, VCS, PR, and network tools are prohibited.
  - Writable roots are confined to the project root; directory traversal, symlink escapes, and reserved paths (`.git`, `.specly`) fail closed.
  - Resource limits (`budget_calls`, `timeout_seconds`) halt execution with a `limited` status and claim no success.
- **Evidence distinction:** An `ExecutionRecord` documents tool outcomes and status, but **never** marks tasks checked or implies requirements acceptance. Local unit tests run against local mock fixtures and contact no external providers.
- **Installation:** Optional extra: `pip install "specly[strands]"`.

## Optional Google AX Cluster Adapter

The optional module `specly_cli.optional.ax_adapter` provides read-only prerequisite diagnostics and effect previews for Google AX / Agent Substrate:

- **Disabled by default:** Default commands never import AX or inspect `KUBECONFIG` / ambient cluster credentials.
- **Offline diagnostics:** Local inspection checks required binaries (`kubectl`, `ko`, `go`) without probing remote clusters or networks.
- **Immutable effect preview:** Previews bind context, namespace, operation, resource targets, and proposed effects to an immutable SHA-256 approval digest.
- **Distinct mutation approval:** Submitting a cluster operation requires affirmative approval matching the preview digest and explicit destination authorization (destination, operation, credential/session). Changing targets or effects invalidates approval and fails closed.
- **Evidence status:** Labeled `unverified` (Google AX prerelease). No live cluster was contacted during local tests.
- **Installation:** Optional extra: `pip install "specly[ax]"`.

## Development & Testing

```bash
# Verify asset synchronization against canonical repository sources
python3 python/scripts/sync_assets.py --check

# Run test suite
PYTHONPATH=python/src python3 -m unittest discover -s python/tests

# Build isolated wheel
uv build --wheel --no-sources
```
