Metadata-Version: 2.4
Name: aqaf
Version: 1.1.0
Summary: Local-first heuristic architecture assessment for AI-assisted software builders
Author: AQAF contributors
License-Expression: MIT
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# AQAF 1.1 — Extensible Architecture Assessment Framework

**Local-first and source-backed architecture review for AI-assisted developers.**

> Catalog: 19 app profiles in four packs. These have **mixed detector coverage**; not 19 complete architecture analyzers. AQAF reports a **provisional, unvalidated heuristic index**, not a certification.


## Repository Owner Manual and training studio

Start with [`REPOSITORY_TUTORIAL_START_HERE.md`](REPOSITORY_TUTORIAL_START_HERE.md) and then [`DOCS_AGENT_HANDOFF.md`](DOCS_AGENT_HANDOFF.md). For a genuine file-by-file introduction, start at [`docs/handbook/README.md`](docs/handbook/README.md) and [`docs/handbook/23-owner-guided-file-walkthrough.md`](docs/handbook/23-owner-guided-file-walkthrough.md). An automatically generated [file inventory](docs/handbook/17-file-catalog.md) describes each repository file, its role and how it should be edited. Six man pages ship under `man/`. The public website includes `/docs/` and `/packages/` pages generated by `scripts/docs/build_handbook.py`. For screencast production, start at [`tutorials/MASTER_AGENT_HANDOFF.md`](tutorials/MASTER_AGENT_HANDOFF.md) and [`tutorials/EP02_FULL_SCRIPT.md`](tutorials/EP02_FULL_SCRIPT.md).

```bash
python3 scripts/docs/build_handbook.py
python3 scripts/docs/verify_handbook.py
bash scripts/docs/rehearse_tutorial.sh
# Windows PowerShell: .\scripts\docs\rehearse_tutorial.ps1
```

HTML and public pack pages are included but **not hosted** until you deploy the website. These are documentation additions to AQAF 1.1.0; scanner rules and scoring have not been changed.

## Try it

```bash
python tools/aqaf.py --version
python tools/aqaf.py profiles list
python tools/aqaf.py packs list
python tools/aqaf.py /path/to/repo --pack web --format md --output ARCHITECTURE_REPORT.md
python tools/aqaf.py /path/to/repo --profile rust_app --format json
python examples/advanced/run_lab.py
```

The Python package can be installed locally from the included wheel. The npm package wraps the **same Python scanner**, not a separate JS engine, and requires Python 3.9+.

### Four specialist packs
- `web` — APIs, SaaS, npm libraries, WordPress, browser extensions.
- `mobile` — Swift and Android.
- `systems` — Rust, Windows client/server, desktop, IoT, multi-repo.
- `automation` — Google Apps Script, CLI, scrapers, AI pipelines, MCP servers.

See `START_HERE_1_1.md`, `packs/`, `docs/PROFILE_AND_PACK_AUTHORING.md`, `distribution/README.md` and `HANDOFF_1_1_MASTER.md`. Advanced examples live in `examples/advanced/`. The website source and optional Cloudflare claim/contact backend are under `website/`.

## Strict safeguards
No target-code execution, offline-by-default, read-only scans, justified suppressions, explicit source/uncertainty and manual validation. External profile files are **data only** and cannot replace built-ins. Source-backed design choices do not make the detection thresholds validated.

Licensed MIT. AQAF is independent and not affiliated with OpenAI, the book authors or example projects.

---

## Original 1.0 reference notes

# AQAF 1.0 — Architecture Quality Assessment Framework

**The quality layer for AI-built software.**

AQAF helps builders who use Codex, Cursor, Claude Code, and other coding agents **inspect architectural risks, choose a defensible target structure, create test-first refactor handoffs, and prevent known regressions**. It is a local-first Python CLI plus reference-backed architecture rules and optional agent workflows.

> **Important:** AQAF 1.0 is an independent, heuristic architecture-review assistant, **not** a certified software quality, security, or performance assessment. The 0–100 index is provisional, not independently calibrated. Passing a scan does not mean production ready.

## 5-minute start (no account, no API key, no upload)

Requires Python 3.9+.

```bash
# Extract this folder and run directly (no installation necessary):
python3 tools/aqaf.py /path/to/project --format md --output architecture-review.md

# Structured report for agents or automation:
python3 tools/aqaf.py /path/to/project --format json --output aqaf-report.json

# Optional install from local folder (offline after wheel build dependencies are available):
python3 -m pip install .
aqaf --version
aqaf /path/to/project --format md
```

**Use Codex next:** copy `handoffs/01_assess_repository.md` into your agent with the report. Codex should return observed facts, unknowns, an architecture trade-off, top risks, tests, a small safe plan, and ADR candidates. **Do not ask it to blindly rewrite your repo.**

## What the tool actually does

| Capability | 1.0 status |
|---|---|
| Heuristic repo scan, no target code execution | Implemented |
| Product profile inference + explicit override | Implemented; may misclassify |
| Provisional quality index and confidence notes | Implemented; **not calibrated** |
| Structured JSON, Markdown, SARIF | Implemented; SARIF is basic and not a security certification |
| Baseline `new` vs `existing` finding comparison | Implemented |
| Suppressions with required written reason | Implemented |
| Opt-in CI failure only for **new** high/medium findings | Implemented |
| Architecture bibliography, rule/source mapping | Included; references do not validate detectors |
| Swift and Rust profiles + Codex review skills | Included; mostly review guidance and heuristics |
| Real repository benchmarks, third-party accuracy validation | **Not done** |
| Hosted UI, GitHub Marketplace listing, payment, licensing server | **Not done** |
| Automatic safe fixes, guaranteed scalability | **Not offered** |

## Baseline workflow

```bash
# Save baseline snapshot in a trusted artifacts directory, NOT auto-edit your code.
python3 tools/aqaf.py ../my-app --format json --output baseline.json

# Compare against the original baseline; only *new* findings can fail CI.
python3 tools/aqaf.py ../my-app --format json --baseline baseline.json --fail-on new-high --output new-report.json

# Generate best-effort SARIF for SARIF-aware consumers:
python3 tools/aqaf.py ../my-app --format sarif --output report.sarif
```

A finding fingerprint changes if its evidence text changes; baseline comparison is intentionally simple, not semantic tracking. Suppressions live in `../my-app/.aqaf.json` (see `templates/aqaf-config.example.json`) and should be documented/periodically reviewed.

## Product profiles

SaaS/web, WordPress plugin, Android, AI pipelines, desktop utility, CLI, scraper/ETL, **Swift**, and **Rust**. The target is never “microservices by default.” See `product_profiles/`, `docs/methodology.md`, and `docs/bibliography.md`.

## Agent skill/handoff material

- `AGENTS.md` — concise core quality guardrails (for development of this framework; adapt for target app).
- `skills/` — architecture assessment, refactor planning, Swift, Rust, and safe framework improvement.
- `handoffs/` — complete product/research/dev/release/sales/support Codex prompts with acceptance criteria.
- `governance/CORE_CONTRACT.md` — rules that agents may not change casually.
- `references/source_registry.json` + `rules/catalog.json` — source-to-rule lineage.

## Distribution / business docs

`launch/` contains a launch checklist, rollout experiments, privacy/support policy drafts, funnel, and readiness gate. `marketing/` contains landing page, pricing hypotheses, content calendar, launch email sequence, demo scripts, objections and customer interview prompts. These are **draft assets**, not claims backed by customers or conversion data.

## Development and validation

```bash
python3 -m unittest discover -s tests -v
python3 -m pip install .
python3 -m aqaf --version
```

Optional build step if `build` is installed: `python3 -m build`. See `docs/validation_plan.md`, `launch/RELEASE_GATE.md` and `tests/` before release.

## Privacy and license

The baseline scanner does not make network requests and does not execute scanned repo code. Scan output may contain local paths and summaries; **review before sharing**. Python source is currently MIT licensed. Commercial documentation, brand/trademark rights, paid service terms and redistribution terms need a deliberate business decision **before selling** (see `launch/IP_AND_LICENSE.md`).

## Documentation map

- `QUICKSTART.md` — first repo scan + Codex workflow
- `docs/bibliography.md` and `references/` — books, standards, references and scope
- `docs/methodology.md`, `docs/scoring.md` — limits of the assessment
- `governance/` — backward compatibility and rule promotion
- `marketing/` — ready-to-edit launch materials
- `handoffs/` — 15 agent handoffs and expected deliverables
- `launch/` — operator checklist and release gate

**No publisher, author, vendor, or reference repository has endorsed AQAF.**

**Version note:** 1.0.0 is the first public-facing version number, rebased from internal 2.2.0. The API and rule engine have *not* undergone independent validation; see PUBLIC_RELEASE_NOTES.md.

## First public release website

The full owner release includes `website/` (Cloudflare Worker + D1 forms, a founding-review request form, contact form, responsive UI) and `offer/` (free review fulfillment template). Website deployment is intentionally operator-configured and cannot accept real submissions without D1 + Turnstile + verified operator contact. See `HANDOFF_MASTER.md`, `PUBLIC_RELEASE_GATE.md` and `website/ops/DEPLOY.md`.
