code-mower 1.4.0__tar.gz → 1.4.2__tar.gz

{code_mower-1.4.0 → code_mower-1.4.2}/MANIFEST.in

@@ -6,6 +6,7 @@ recursive-include src/code_mower/templates/product-support *
 include src/code_mower/*.json
 recursive-include templates *.j2 *.json *.md *.yml *.yaml
 recursive-include templates/lanes *
+recursive-include docs *.md
 include requirements/*.txt
 include LICENSE
 include NOTICE

{code_mower-1.4.0 → code_mower-1.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-mower
-Version: 1.4.0
+Version: 1.4.2
 Summary: Multi-reviewer AI code audit orchestration
 License-Expression: Apache-2.0
 Project-URL: Homepage, https://github.com/codemower-ai/code-mower
@@ -45,13 +45,14 @@ The current release is supervised-pilot, bring-your-own-agent-loop software.
 It is not a drop-in unattended merge gate. Humans still own credentials,
 repository policy, reviewer promotion, and exceptional decisions.
 
-The current package-index release baseline is `v1.4.0`, with pinned package
-install spec `code-mower==1.4.0`. Release evidence is recorded on the GitHub
-release and in the first-user install rehearsal.
+The current source candidate is `v1.4.2`, with target install spec
+`code-mower==1.4.2`. Publication and installed-package qualification are pending
+[#952](https://github.com/codemower-ai/code-mower/issues/952). The published
+`v1.4.0` and `v1.4.1` artifacts remain unchanged. Install commands below target
+v1.4.2 after publication; candidate rehearsals use the exact verified artifact.
 
-Documentation on `main` follows the source on `main`. When using the published
-package, start with the
-[`v1.4.0` guide](https://github.com/codemower-ai/code-mower/blob/v1.4.0/docs/try-in-10-minutes.md).
+Documentation on `main` follows the source on `main`. After v1.4.2 publication, start with the
+[`v1.4.2` guide](https://github.com/codemower-ai/code-mower/blob/v1.4.2/docs/try-in-10-minutes.md).
 
 ## What Code Mower Adds
 
@@ -79,7 +80,7 @@ one stable `pipx` installation:
 ```bash
 python3.12 --version
 export CODE_MOWER_PYTHON="$(command -v python3.12)"
-pipx install --python "$CODE_MOWER_PYTHON" code-mower==1.4.0
+pipx install --python "$CODE_MOWER_PYTHON" code-mower==1.4.2
 command -v code-mower
 code-mower --version
 ```
@@ -140,10 +141,16 @@ code-mower session start \
 `session start` saves an operating brief and takes the local single-orchestrator
 lease. It does not launch every selected product. The host uses the execution
 paths available for each participant and records explicit handoffs where Code
-Mower has no automatic transport.
+Mower has no automatic transport. Later, from anywhere in the checkout,
+`code-mower session show --current` finds the brief the live lease names and
+`code-mower session lease show` reports the lease itself; neither changes state.
+The default is 12 hours. A later process can renew or release the same session
+ID with `session lease renew --session-id SESSION_ID` or `session lease release
+--session-id SESSION_ID`; stop its writers before release. Use `session start
+--dry-run` or `--no-lease` for read-only work.
 
 Codex, Claude Code, and Cursor are qualified for the shared session, telemetry,
-lease, and Jira-authority contract in v1.4.0. Devin, Grok Bot, Antigravity,
+lease, and Jira-authority contract in v1.4.2. Devin, Grok Bot, Antigravity,
 Muse, and custom hosts are recognized for briefs and provenance, while their
 execution remains an explicit handoff or provider-specific transport. See
 [Participants And Sessions](docs/sessions.md) and the
@@ -251,11 +258,11 @@ and the [Cloud Data Contract](docs/cloud-data-contract.md).
 
 ## Current Capabilities And Limits
 
-| Area | v1.4.0 posture |
+| Area | v1.4.2 posture |
 | --- | --- |
 | Default builders and reviewers | Claude Code + Codex |
 | Session hosts | Codex, Claude Code, and Cursor qualified; other identities recognized but require explicit handoff/provider transport |
-| Devin | Maintained local builder and hosted release-qualification transport; local review remains informational and Devin is not yet a qualified peer orchestrator |
+| Devin | Maintained local builder lane and an exact PR-bound hosted work-order library seam (`code_mower.devin_work_orders`, no packaged CLI command); local review remains informational and Devin is not yet a qualified peer orchestrator |
 | Organizational context | Optional Coworker delivery to approved Claude/Codex/Devin roles |
 | Work trackers | GitHub Issues by default; Jira Cloud is optional and guarded |
 | Forge and merge gate | GitHub |
@@ -264,8 +271,8 @@ and the [Cloud Data Contract](docs/cloud-data-contract.md).
 | Slack | Command and authenticated bounded ingress foundation only; no Slack worker delivery, results, or orchestration authority |
 
 GitLab, Bitbucket, broad unattended rollout, uncalibrated merge gates, Devin
-peer-orchestrator/reviewer parity, a required Graphify dependency, and Slack
-worker delivery are not shipped in v1.4.0. The current priorities and
+peer-orchestrator/reviewer parity, a hosted work-order CLI, a required Graphify
+dependency, and Slack worker delivery are outside the v1.4.2 candidate. The current priorities and
 boundaries are recorded in
 [Current State And Roadmap](docs/current-state-and-roadmap.md).
 
@@ -278,7 +285,7 @@ boundaries are recorded in
 - [Upgrade An Existing Repository](docs/upgrade-existing-repo.md)
 - [Quickstart Reference](docs/quickstart.md)
 - [Troubleshooting](docs/troubleshooting.md)
-- [First Run Transcript](docs/first-run-transcript.md)
+- [First Run Transcript](docs/first-run-transcript.md) (v1.4.0 illustrative shape, not the current v1.4.2 pin)
 
 ### Sessions, Builders, And Reviewers
 
@@ -320,7 +327,7 @@ boundaries are recorded in
 - [Cloud Data Contract](docs/cloud-data-contract.md)
 - [Release Qualification](docs/release-qualification.md)
 - [Public Release Checklist](docs/public-release-checklist.md)
-- [v1.4.0 Release Notes](docs/v140-release-notes.md)
+- [v1.4.2 Release Notes](docs/v142-release-notes.md)
 - [Release History And Archived Plans](docs/release-history.md)
 - [Changelog](CHANGELOG.md)
 - [Contributing](CONTRIBUTING.md)

{code_mower-1.4.0 → code_mower-1.4.2}/README.md

@@ -9,13 +9,14 @@ The current release is supervised-pilot, bring-your-own-agent-loop software.
 It is not a drop-in unattended merge gate. Humans still own credentials,
 repository policy, reviewer promotion, and exceptional decisions.
 
-The current package-index release baseline is `v1.4.0`, with pinned package
-install spec `code-mower==1.4.0`. Release evidence is recorded on the GitHub
-release and in the first-user install rehearsal.
+The current source candidate is `v1.4.2`, with target install spec
+`code-mower==1.4.2`. Publication and installed-package qualification are pending
+[#952](https://github.com/codemower-ai/code-mower/issues/952). The published
+`v1.4.0` and `v1.4.1` artifacts remain unchanged. Install commands below target
+v1.4.2 after publication; candidate rehearsals use the exact verified artifact.
 
-Documentation on `main` follows the source on `main`. When using the published
-package, start with the
-[`v1.4.0` guide](https://github.com/codemower-ai/code-mower/blob/v1.4.0/docs/try-in-10-minutes.md).
+Documentation on `main` follows the source on `main`. After v1.4.2 publication, start with the
+[`v1.4.2` guide](https://github.com/codemower-ai/code-mower/blob/v1.4.2/docs/try-in-10-minutes.md).
 
 ## What Code Mower Adds
 
@@ -43,7 +44,7 @@ one stable `pipx` installation:
 ```bash
 python3.12 --version
 export CODE_MOWER_PYTHON="$(command -v python3.12)"
-pipx install --python "$CODE_MOWER_PYTHON" code-mower==1.4.0
+pipx install --python "$CODE_MOWER_PYTHON" code-mower==1.4.2
 command -v code-mower
 code-mower --version
 ```
@@ -104,10 +105,16 @@ code-mower session start \
 `session start` saves an operating brief and takes the local single-orchestrator
 lease. It does not launch every selected product. The host uses the execution
 paths available for each participant and records explicit handoffs where Code
-Mower has no automatic transport.
+Mower has no automatic transport. Later, from anywhere in the checkout,
+`code-mower session show --current` finds the brief the live lease names and
+`code-mower session lease show` reports the lease itself; neither changes state.
+The default is 12 hours. A later process can renew or release the same session
+ID with `session lease renew --session-id SESSION_ID` or `session lease release
+--session-id SESSION_ID`; stop its writers before release. Use `session start
+--dry-run` or `--no-lease` for read-only work.
 
 Codex, Claude Code, and Cursor are qualified for the shared session, telemetry,
-lease, and Jira-authority contract in v1.4.0. Devin, Grok Bot, Antigravity,
+lease, and Jira-authority contract in v1.4.2. Devin, Grok Bot, Antigravity,
 Muse, and custom hosts are recognized for briefs and provenance, while their
 execution remains an explicit handoff or provider-specific transport. See
 [Participants And Sessions](docs/sessions.md) and the
@@ -215,11 +222,11 @@ and the [Cloud Data Contract](docs/cloud-data-contract.md).
 
 ## Current Capabilities And Limits
 
-| Area | v1.4.0 posture |
+| Area | v1.4.2 posture |
 | --- | --- |
 | Default builders and reviewers | Claude Code + Codex |
 | Session hosts | Codex, Claude Code, and Cursor qualified; other identities recognized but require explicit handoff/provider transport |
-| Devin | Maintained local builder and hosted release-qualification transport; local review remains informational and Devin is not yet a qualified peer orchestrator |
+| Devin | Maintained local builder lane and an exact PR-bound hosted work-order library seam (`code_mower.devin_work_orders`, no packaged CLI command); local review remains informational and Devin is not yet a qualified peer orchestrator |
 | Organizational context | Optional Coworker delivery to approved Claude/Codex/Devin roles |
 | Work trackers | GitHub Issues by default; Jira Cloud is optional and guarded |
 | Forge and merge gate | GitHub |
@@ -228,8 +235,8 @@ and the [Cloud Data Contract](docs/cloud-data-contract.md).
 | Slack | Command and authenticated bounded ingress foundation only; no Slack worker delivery, results, or orchestration authority |
 
 GitLab, Bitbucket, broad unattended rollout, uncalibrated merge gates, Devin
-peer-orchestrator/reviewer parity, a required Graphify dependency, and Slack
-worker delivery are not shipped in v1.4.0. The current priorities and
+peer-orchestrator/reviewer parity, a hosted work-order CLI, a required Graphify
+dependency, and Slack worker delivery are outside the v1.4.2 candidate. The current priorities and
 boundaries are recorded in
 [Current State And Roadmap](docs/current-state-and-roadmap.md).
 
@@ -242,7 +249,7 @@ boundaries are recorded in
 - [Upgrade An Existing Repository](docs/upgrade-existing-repo.md)
 - [Quickstart Reference](docs/quickstart.md)
 - [Troubleshooting](docs/troubleshooting.md)
-- [First Run Transcript](docs/first-run-transcript.md)
+- [First Run Transcript](docs/first-run-transcript.md) (v1.4.0 illustrative shape, not the current v1.4.2 pin)
 
 ### Sessions, Builders, And Reviewers
 
@@ -284,7 +291,7 @@ boundaries are recorded in
 - [Cloud Data Contract](docs/cloud-data-contract.md)
 - [Release Qualification](docs/release-qualification.md)
 - [Public Release Checklist](docs/public-release-checklist.md)
-- [v1.4.0 Release Notes](docs/v140-release-notes.md)
+- [v1.4.2 Release Notes](docs/v142-release-notes.md)
 - [Release History And Archived Plans](docs/release-history.md)
 - [Changelog](CHANGELOG.md)
 - [Contributing](CONTRIBUTING.md)

code_mower-1.4.2/docs/acp-bridge-spike.md

@@ -0,0 +1,48 @@
+# Code Mower ACP Bridge Spike
+
+Agent Client Protocol is a JSON-RPC-over-stdio protocol for driving coding-agent CLIs through a provider-neutral client. Code Mower should treat it as a research lane until one provider can run a full head-bound audit through it without weakening the existing audit invariants.
+
+## Goal
+
+Replace per-provider shell-and-parse glue with one client primitive where the underlying CLI supports ACP.
+
+The first useful proof is an informational audit lane that:
+
+- accepts repo, PR number, head SHA, prompt lenses, and artifact output path;
+- starts the configured ACP command from `CODE_MOWER_ACP_COMMAND`;
+- sends the same trusted review doctrine used by other audit wrappers;
+- records stdout/stderr/session metadata in a held blind-review artifact;
+- emits a normal trailer-bearing audit comment only after schema validation.
+
+Hermes Agent is a good future candidate because its documentation exposes
+ACP-related surfaces. The first plain `hermes-cli` one-shot calibration now
+exists and showed useful #347 signal, but also a known-clean blocker, an
+infra/parse failure, and audit-input gaps on large historical diffs. That moves
+Hermes from "unknown" to "interesting but not boring." ACP should reduce adapter
+churn only after the provider runtime, auth, prompt, head-SHA, context-pack,
+parser, and artifact contracts are already boring.
+
+## Non-goals
+
+- Do not make ACP a merge-authority lane during the spike.
+- Do not import long-lived conversational state into Code Mower. Audits stay stateless and head-bound.
+- Do not bypass existing wrappers for providers that already have reliable structured lanes.
+- Do not use ACP as a dashboard, IDE, browser, or human cockpit surface.
+
+## Acceptance Criteria
+
+1. `code-mower doctor --profile cli_research` reports the configured ACP command and protocol.
+2. A fixture-backed client test proves request/response framing without requiring a live provider.
+3. A dry-run audit can generate a held artifact without posting a merge signal.
+4. The bridge refuses to produce a done/blocked trailer when the response is missing the expected schema or head SHA.
+5. The provider catalog continues to mark `acp_bridge` as manual and informational.
+
+## Open Questions
+
+- Which provider should be the first proof case?
+- Does Hermes' ACP surface preserve the same stateless, head-bound audit
+  invariants as its one-shot CLI path?
+- Can an ACP-backed Hermes proof resolve the #390 context/input gap better than
+  the one-shot CLI without importing long-lived session state?
+- Should ACP responses use the provider's native schema, or should Code Mower require a normalized audit schema at the bridge boundary?
+- Can the client capture enough token, model, and elapsed-time metadata for spend/value analytics without provider-specific code?

code_mower-1.4.2/docs/architecture.md

@@ -0,0 +1,205 @@
+# Architecture
+
+Code Mower is a local-first Python CLI plus generated GitHub support files. It
+coordinates supervised AI builder and reviewer lanes, records bounded evidence,
+and can optionally upload sanitized metadata to CodeMower.com.
+
+## Product Boundaries
+
+Code Mower owns:
+
+- participant and role selection;
+- operating briefs, work orders, local session leases, and recovery state;
+- builder provenance and delivery outcomes;
+- reviewer invocation, structured verdicts, and current-head validity;
+- calibration, lane-promotion evidence, and local reports;
+- generated GitHub labels, workflows, gates, and support wrappers;
+- guarded tracker operations; and
+- explicit context and cloud-data boundaries.
+
+Provider products still own their models, authentication, execution sandboxes,
+usage charges, and product-specific sessions. GitHub remains authoritative for
+pull requests, checks, and merge state. Selecting a provider does not grant it
+review or merge authority.
+
+## Core Concepts
+
+- **Participant:** a selected product identity such as Claude, Codex, or Devin.
+- **Provider transport:** the CLI, API, GitHub app, or manual handoff used for a
+  participant's specific job.
+- **Orchestrator:** the hosting agent by default; coordinates assignments,
+  evidence, reviews, and recovery.
+- **Builder:** the single writer for one branch.
+- **Reviewer lane:** a provider plus trigger, prompt/lens, verdict contract, and
+  merge posture.
+- **Context provider:** a source of approved bounded evidence. It is separate
+  from participant roles.
+- **Session:** a local operating brief, selected participants, optional work
+  item/context association, and single-orchestrator lease.
+- **Calibration corpus:** known-clean, known-blocked, or subtle-risk cases used
+  to measure reviewer usefulness.
+- **Builder experiment:** a source-free measurement record for an authoring
+  attempt and its review/merge outcome.
+- **Cloud bundle:** an inspectable export that uploads only after an explicit
+  command.
+
+## Runtime Shape
+
+```mermaid
+flowchart LR
+  U["CLI / hosting agent"] --> S["Session and work order"]
+  S --> P["Participant/provider transports"]
+  P --> B["Builder: one branch writer"]
+  P --> R["Independent reviewers"]
+  C["Optional context provider"] --> S
+  B --> G["GitHub pull request"]
+  R --> G
+  G --> M["Gate and repository merge policy"]
+  S --> L["Local Board, calibration, reports"]
+  L --> X{"Explicit cloud upload?"}
+  X -->|No| K["Keep local"]
+  X -->|Yes| H["CodeMower.com metadata"]
+```
+
+`code-mower session start` creates the operating state and lease. It does not
+act as a universal process launcher. The host invokes a maintained local or
+hosted transport where one exists and otherwise records an explicit handoff.
+
+## Package Layout
+
+```text
+src/code_mower/
+  cli.py                         top-level command routing
+  init.py, next_steps.py         setup and first-run guidance
+  session.py                     participant brief and orchestrator lease
+  context_session.py             protected guided context state
+  context_guided.py              prepare/deliver/attach/feedback workflow
+  context_*.py                   connection, packet, delivery, and review contracts
+  doctor.py                      thin doctor CLI adapter
+  doctor_checks/                 runtime, provider, GitHub, tracker, cloud checks
+  participants.py               participant identity and role mapping
+  provider_registry.py           reviewer lane metadata and posture
+  providers/                     shared provider metadata helpers
+  provider_runners/              checkout, process, verdict, and GitHub primitives
+  lane_configs/                  provider-specific lane declarations
+  *_audit_pr.py                  provider-specific audit adapters
+  work_orders.py                 planning and implementation contracts
+  builder_runs.py                source-free builder provenance
+  calibration/                   corpus, evidence, policy, metrics, reports
+  tracker_*.py, jira_*.py        work-item contracts and guarded Jira operations
+  cloud.py, cloud_client/        export, upload, setup, and metadata operations
+  package_*.py, migration_*.py   generated package and rehearsal support
+  templates/                     generated config, workflows, prompts, wrappers
+tests/                           behavior, privacy, and release-hygiene tests
+scripts/                         smoke, privacy, fresh-clone, and Python helpers
+docs/                            current guides and historical release records
+```
+
+Shared provider-runner modules implement stable mechanics such as isolated PR
+checkouts, subprocess cleanup, verdict artifacts, and GitHub posting. Provider
+adapters retain authentication, sandbox, prompt, parser, and API differences.
+The goal is one role contract, not identical vendor mechanics.
+
+## Session And Participant Contract
+
+Participant selection is independent from role and merge authority. A session
+stores normalized participants and host identity. Repository configuration and
+the reviewer registry decide which transports and review policies apply.
+
+One local working copy can have one mutating orchestrator lease. One PR branch
+can have one writer. These are different controls: the session lease prevents
+two orchestrators from coordinating the same working copy, while the branch
+rule prevents a reviewer or second builder from changing the owner's branch.
+
+Codex, Claude Code, and Cursor are qualified session hosts in v1.4.0. Other host
+identities can receive the same brief and telemetry shape, but Code Mower does
+not claim execution parity until the relevant transport and recovery behavior
+are qualified. See [Participants And Sessions](sessions.md).
+
+## Review And Merge Contract
+
+Reviewers consume the PR diff and task/context contract, not the builder's raw
+transcript. Structured verdicts bind to the exact PR head. When required
+context is selected, they also bind to the current context input revision.
+
+Generated workflows clear stale terminal audit labels after the head changes.
+The repository gate combines current trusted verdict evidence with configured
+policy. A reviewer starts informational unless its repository-specific
+known-clean and known-blocked evidence supports promotion.
+
+The private [Devin review adapters](devin-review-parity.md) normalize local CLI
+and hosted v3 evidence over the existing remote lifecycle. Both remain
+informational and revalidate the current head and context before consumption.
+
+## Context Contract
+
+Context connections are private machine state. Repository configuration stores
+only a generic connection alias and policy. Packets retain bounded evidence,
+citations, provenance, expiry, and integrity metadata in a protected local
+store.
+
+The provider adapter may fetch or authorize evidence, but the common Code Mower
+packet, delivery, attachment, and review contracts decide how it enters a work
+order or review. Every delivery reauthorizes. Context providers gain no role or
+tracker authority. See [Context Provider Contract](context-provider-contract.md).
+
+## Tracker Contract
+
+`code_mower.trackerWorkItem.v1` normalizes a bounded work item. GitHub Issues is
+the default. Jira Cloud is opt-in; queue reads and all writes use Code Mower's
+REST transport. Writes require both repository configuration and an explicit
+apply command and are revalidated against live scope. Connected Atlassian MCP
+can enrich local reading but cannot authorize a mutation. See
+[Work Tracker Data Contract](tracker-data-contract.md).
+
+## Local And Cloud Boundary
+
+Local runners hold source, diffs, credentials, worktrees, prompts, raw provider
+output, and private context. The Board reads redacted local/GitHub metadata and
+serves on loopback. It does not upload data.
+
+Cloud export is a separate explicit operation. Default uploads exclude source,
+raw diffs, raw model transcripts, raw stdout/stderr, auth output, issue body
+text, credentials, and private context. Provider verdict artifacts and cloud
+events pass Code Mower-owned schema and privacy validation before posting or
+upload. See [Cloud Data Contract](cloud-data-contract.md).
+
+## First-Run Flow
+
+```mermaid
+flowchart TD
+  A["Install pinned package"] --> B["Preview init --easy"]
+  B --> C["Generate reviewable setup"]
+  C --> D["doctor --adoption"]
+  D --> E["Open setup PR"]
+  E --> F["Run manual Codex and Claude audits"]
+  F --> G["Inspect lane status and local reports"]
+  G --> H{"Add automation?"}
+  H -->|No| I["Continue manual supervised pilot"]
+  H -->|Yes| J["Configure dispatch, gate, and runner"]
+```
+
+Automation credentials and auto-merge configuration follow the first manual
+audit. Optional Coworker context, additional participants, Jira, and cloud
+sharing are independent additions.
+
+## Release Validation
+
+From a contributor checkout:
+
+```bash
+scripts/dev-python -m venv .venv
+.venv/bin/python -m pip install -e ".[test]"
+.venv/bin/python -m ruff check .
+.venv/bin/python -m unittest discover -s tests
+.venv/bin/python scripts/privacy_scan.py
+.venv/bin/python scripts/smoke_easy_mode.py \
+  --code-mower-bin .venv/bin/code-mower --json
+.venv/bin/python scripts/fresh_clone_rehearsal.py \
+  --repo-url . --ref HEAD --python .venv/bin/python --json
+git diff --check
+```
+
+Package-index publication and live provider campaigns are separate release
+checks. See [Public Release Checklist](public-release-checklist.md) and
+[Release Qualification](release-qualification.md).

code_mower-1.4.2/docs/archive/README.md

@@ -0,0 +1,11 @@
+# Archived Release Rehearsals
+
+These notes are historical release-gate evidence from the alpha line. They are
+kept for maintainers who need to reconstruct how the package path evolved, but
+they are not first-user documentation.
+
+For the current install rehearsal, use
+[`../first-user-install-rehearsal.md`](../first-user-install-rehearsal.md).
+For the current quickstart, use [`../quickstart.md`](../quickstart.md) or
+[`../try-in-10-minutes.md`](../try-in-10-minutes.md).
+

code_mower-1.4.2/docs/archive/first-user-install-rehearsal-alpha4.md

@@ -0,0 +1,106 @@
+# v0.5.0-alpha.4 First-User Install Rehearsal
+
+This is the recorded release-gate shape for `v0.5.0-alpha.4`. It proves the
+source checkout can install, run easy mode, generate a starter value report, and
+create a metadata-only cloud dry-run bundle from a fresh toy repository.
+
+The exact temporary paths and cache output vary by machine; the important signal
+is the command sequence and `status: pass` results.
+
+## Local Source Install
+
+```bash
+scripts/dev-python -m venv .venv
+.venv/bin/python -m pip install --upgrade pip
+.venv/bin/python -m pip install -e . ruff build
+.venv/bin/code-mower --version
+```
+
+Expected output:
+
+```text
+code-mower 0.5.0a4
+```
+
+## Release Gate
+
+```bash
+.venv/bin/python -m ruff check .
+.venv/bin/python scripts/privacy_scan.py
+.venv/bin/python -m unittest discover -s tests
+.venv/bin/python -m compileall -q src scripts
+.venv/bin/python -m build
+```
+
+Observed summary:
+
+```text
+All checks passed!
+privacy scan passed
+Ran 54 tests ... OK
+Successfully built code_mower-0.5.0a4.tar.gz and code_mower-0.5.0a4-py3-none-any.whl
+```
+
+`python -m build` currently emits non-blocking warnings about the deprecated
+`project.license` table form and broad YAML include patterns. The alpha.4 build
+also verifies bytecode caches are excluded from the wheel even after
+`compileall` runs.
+
+## Easy-Mode Smoke
+
+```bash
+.venv/bin/python scripts/smoke_easy_mode.py \
+  --code-mower-bin .venv/bin/code-mower \
+  --json
+```
+
+Observed summary:
+
+```json
+{
+  "mode": "code-mower-easy-mode-smoke",
+  "status": "pass"
+}
+```
+
+The smoke covers:
+
+- `code-mower providers list`
+- `code-mower init --easy --apply`
+- generated `smoke-tests.sh`
+- `code-mower doctor --easy --json`
+- wrapper rehearsal
+- calibration plan/evidence/metrics/policy/value-report
+- cloud export
+- cloud upload dry run
+
+## Fresh-Clone Rehearsal
+
+After committing the alpha.4 changes, run:
+
+```bash
+.venv/bin/python scripts/fresh_clone_rehearsal.py \
+  --repo-url /absolute/path/to/code-mower \
+  --ref HEAD \
+  --python .venv/bin/python \
+  --work-dir /tmp/code-mower-alpha4-fresh-clone \
+  --json
+```
+
+Expected summary:
+
+```json
+{
+  "mode": "code-mower-fresh-clone-rehearsal",
+  "status": "pass"
+}
+```
+
+Observed alpha.4 summary:
+
+```text
+Successfully installed PyYAML-6.0.3 code-mower-0.5.0a4
+No broken requirements found.
+code-mower 0.5.0a4
+status: pass
+```