Metadata-Version: 2.2
Name: adlc-engineering
Version: 0.9.2
Summary: Agentic Development Lifecycle contracts, schemas, runtime adapters, and deterministic validators.
Author: Eric Freeman
License: MIT License
        
        Copyright (c) 2026 Eric Freeman
        
        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.
        
Project-URL: Homepage, https://github.com/bigeasyfreeman/adlc
Project-URL: Repository, https://github.com/bigeasyfreeman/adlc
Project-URL: Issues, https://github.com/bigeasyfreeman/adlc/issues
Project-URL: Changelog, https://github.com/bigeasyfreeman/adlc/blob/main/CHANGELOG.md
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: jsonschema<5.0,>=4.0
Provides-Extra: pdf
Requires-Dist: PyMuPDF<2.0,>=1.24; extra == "pdf"
Provides-Extra: audit
Requires-Dist: pip-audit>=2.7; extra == "audit"
Requires-Dist: radon>=6; extra == "audit"
Requires-Dist: ruff>=0.5; extra == "audit"
Requires-Dist: vulture>=2.11; extra == "audit"
Requires-Dist: mypy>=1.10; extra == "audit"
Provides-Extra: docs
Requires-Dist: mkdocs==1.6.1; extra == "docs"
Requires-Dist: mkdocs-material==9.7.6; extra == "docs"
Requires-Dist: playwright==1.60.0; extra == "docs"

# ADLC

[![CI](https://github.com/bigeasyfreeman/adlc/actions/workflows/ci.yml/badge.svg)](https://github.com/bigeasyfreeman/adlc/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

Run repeatable Build, Fix, and Review loops with your coding agent, with every completion claim tied to evidence.

ADLC gives an existing coding agent one public skill and a deterministic control plane for state, permissions, verification, approvals, recovery, and evidence. It does not replace the agent or silently merge, deploy, publish, or spend money.

## Install in 30 seconds

Install the scoped public beta from the `adlc-engineering` distribution, then use the transactional lifecycle to install and diagnose one canonical skill:

```bash
python3 -m pip install "adlc-engineering==0.9.2"
adlc-skill install --provider codex --target /path/to/your-repo
adlc-skill doctor --provider codex --target /path/to/your-repo
```

Use `claude` instead of `codex` for Claude Code. The package lifecycle (`install`, `doctor`, `update`, `rollback`, and `uninstall`) is the transactional path for those two providers. Cursor, Antigravity, and Factory are experimental compatibility targets without rollback claims. See [installation](docs/start/installation.md) for exact ownership and migration behavior.

## Run a five-minute Fix

In the target repository, ask the installed coding agent:

```text
/adlc fix the failing average calculation. Reproduce it first, make the smallest repair, run the affected tests, and stop with PR-ready evidence.
```

The expected sequence is red verifier → bounded repair → green verifier → independent review → `pr_ready`. To replay the repository’s deterministic version of that first success in an isolated temporary repository:

```bash
bash tests/acceptance/run_readme_quickstart.sh
```

That replay routes Fix through the installed public facade, then proves the deterministic kernel path. It does not invoke Codex or make a live-provider claim. The [First Fix guide](docs/start/first-fix.md) explains every stop state and artifact.

## Three evidence-bound loops

| Loop | Use it when | Honest terminal outcome |
|---|---|---|
| Build | Approved intent needs to become a bounded change. | A scoped diff and declared evidence are `pr_ready`, or the run names what blocked. |
| Fix | A defect can be reproduced. | Red-to-green defect proof and affected-suite evidence are `pr_ready`, or reproduction/verification remains blocked. |
| Review | A concrete change needs independent scrutiny. | Read-only findings and a verdict; remediation requires a separate Build or Fix invocation. |

Start with the [Build](docs/guides/build.md), [Fix](docs/guides/fix.md), or [Review](docs/guides/review.md) guide. Resume interrupted work without replaying completed effects with the [Resume guide](docs/guides/resume.md).

## Current provider evidence

<!-- BEGIN GENERATED SUPPORT MATRIX -->
| Provider | Provider version | Harness | Loop | Label | Dimensions | Runs | Evidence commit |
|---|---:|---|---|---|---|---:|---|
| Codex | 0.137.0 | codex-cli-installed-skill | Fix | beta | installation, invocation, behavior, end-to-end: pass | 3 | `4a629f313ee4` |
| Claude Code | 2.1.210 | claude-code-credential-preflight | Fix | — | invocation: blocked (`credentials_missing`); remaining dimensions: not run | 1 failed preflight | `ea1f2d193bc2` |
<!-- END GENERATED SUPPORT MATRIX -->

This block is checked against [`support-matrix.json`](docs/evidence/provider-conformance/support-matrix.json); edit the evidence, then run `python3 scripts/render_support_matrix.py`, rather than hand-editing claims. Labels apply only to the named provider, version, harness, model, loop, fixture, commit, and dimensions. See the [generated support matrix](docs/trust/support-matrix.md) for raw evidence links and limitations.

## How it works

```text
your intent
    │
    ▼
one `adlc` skill ──► Build / Fix / Review loop contract
    │                              │
    ▼                              ▼
coding-agent judgment       deterministic ADLC kernel
                             state · admission · tests
                             approvals · recovery · evidence
                                      │
                                      ▼
                         proved / blocked / awaiting human
```

The skill routes only the context needed for the selected command. The kernel owns deterministic truth and fails closed when approval, credentials, evidence, or compatibility proof is missing. Read [skills, loops, and kernel](docs/concepts/skills-loops-kernel.md) for the boundary.

## Safety and human approval

- Review, status, and doctor are read-only.
- Local mutation starts only inside an authorized Build or Fix boundary.
- External writes, publish, merge, release, deploy, destructive recovery, privileged access, and paid execution require explicit approval.
- Persisted effects carry idempotency evidence so resume does not intentionally replay completed work.
- Telemetry is off by default. Provider credentials and target-repository content stay under the operator’s provider and repository controls.
- `pr_ready` does not mean merged, deployed, adopted, secure, or generally available.

Read the [security and privacy boundary](docs/trust/security-privacy.md), [security policy](SECURITY.md), and [compatibility/deprecation policy](docs/trust/compatibility-deprecation.md).

## Proof, not promises

- [Provider conformance evidence](docs/evidence/provider-conformance/README.md)
- [Deterministic public Fix replay](tests/acceptance/run_public_fix_loop.sh)
- [Replayable invoice Fix demo and public benchmark](docs/trust/benchmark.md)
- [Legacy-surface migration ledger](docs/migration/legacy-surface-migration.md)
- [Canonical local verification](docs/contribute/development.md)

The public benchmark preserves three live Codex runs plus an independent three-run replay, with exact red-before-green verification, same-session interrupt/resume, one-file scope, distinct read-only review, and completion-audit evidence. Its versioned report discloses provider/model versions, tokens, duration, marginal account cost, failures, and limitations. These proofs are scoped evidence, not proof of future behavior, market traction, compliance certification, GA readiness, or universal provider support.

## Public beta candidate

The 0.9.2 beta launch packet accompanies the immutable release candidate. It includes the
[technical narrative](docs/launch/technical-article.md), [five-minute demo and
recording plan](docs/launch/demo-script.md), [local-first metric
definitions](docs/launch/metrics.md), and [beta operating
model](docs/launch/beta-operations.md). Every launch claim resolves to repository
evidence, telemetry remains off, and package, GitHub Release, Pages, and launch
communication actions remain human-approval-bound and must be verified at their public endpoints.

Use the beta feedback issue template for sanitized product outcomes and
friction. Do not put vulnerabilities, credentials, prompts, source code, private
paths, or target-repository content in a public issue; use the private Security
Advisory path instead.

The beta learning funnel is intentionally local and ordered:

<!-- BEGIN BETA FUNNEL -->
1. **README visit.** Confirm that the evidence boundary and current provider row
   match the intended use.
2. **Install.** Complete the pinned package install shown above.
3. **Doctor.** Run `adlc-skill doctor` and proceed only when required checks pass.
4. **First loop.** Run the five-minute Fix path, or an eligible Build, and retain
   its local evidence-backed terminal report.
5. **Returning project.** Within seven days, start another eligible Build, Fix,
   or Review in the same project; this is a local learning signal, not a
   retention or traction claim.
<!-- END BETA FUNNEL -->

## Documentation and community

- [Documentation home](docs/index.md)
- [Public command reference](docs/reference/public-commands.md)
- [Configuration](docs/reference/configuration.md)
- [Artifacts and schemas](docs/reference/artifacts-and-schemas.md)
- [Stop reasons](docs/reference/stop-reasons.md)
- [Contributing](CONTRIBUTING.md) and [governance](GOVERNANCE.md)
- [Code of Conduct](CODE_OF_CONDUCT.md)
- [Changelog](CHANGELOG.md)
- [Migration guide](docs/migration/legacy-surface-migration.md) and [historical archive](docs/archive/README.md)

## Status and limitations

ADLC is an unreleased beta candidate. The source checkout, deterministic tests, exact Codex Fix configuration shown above, documentation-site build, scoped live public benchmark, secure release preparation, and final-form launch packet have evidence; package publication, production docs deployment, and public communication remain human-gated. Only released and tested configurations may graduate support labels.

`doc_honesty_section`: This page describes the current source product and links to its evidence; it is not a release artifact or adoption proof.

`no_overclaim`: ADLC does not claim GA, autonomous delivery, universal provider behavior, benchmark superiority, compliance certification, or production support.

`limitations`: Current live-provider evidence covers only the exact Codex Fix row above. Claude Code invocation is credential-blocked in the recorded run, and compatibility targets are not live-provider claims.

## License

MIT. See [LICENSE](LICENSE).
