### ArtifactDiff README quickstart commands

Source: https://github.com/wfengq/artifactdiff/blob/master/docs/superpowers/plans/2026-08-04-contract-corpus-release.md

Shell commands to install ArtifactDiff, create and seal a policy, verify a contract edit, and review the bundle. These are the primary CLI commands for the quickstart tutorial.

```bash
pipx install artifactdiff
artifactdiff policy create contract.docx -o change-policy.yaml
artifactdiff policy seal contract.docx change-policy.yaml -o change-policy.sealed.json
artifactdiff verify contract.docx edited.docx --policy change-policy.sealed.json --output review-bundle
artifactdiff review review-bundle
```

--------------------------------

### Configure MCP roots and start artifactdiff-mcp

Source: https://github.com/wfengq/artifactdiff/blob/master/README.md

Environment configuration for starting the MCP stdio server: set absolute, path-separator-delimited input and output roots before running artifactdiff-mcp. MCP intentionally cannot approve findings or perform verified signing.

```text
ARTIFACTDIFF_MCP_INPUT_ROOTS=/absolute/contracts
ARTIFACTDIFF_MCP_OUTPUT_ROOTS=/absolute/artifactdiff-output
artifactdiff-mcp
```

--------------------------------

### Run the Golden Path demo

Source: https://github.com/wfengq/artifactdiff/blob/master/README.md

Install dependencies and execute the synthetic contract verification workflow.

```console
python -m venv .venv
# Activate .venv using your shell, then:
python -m pip install -e ".[dev]"
python scripts/run_contract_golden_path.py --output build/contract-golden-path
python -m json.tool build/contract-golden-path/summary.json
```

--------------------------------

### Install dev dependencies and run tests

Source: https://github.com/wfengq/artifactdiff/blob/master/README.md

Install the package in editable mode with development dependencies and run the test suite quietly. The repository includes unit, integration, tamper, CLI, MCP, review-desk, cross-format, and signed Golden Path acceptance coverage.

```console
python -m pip install -e ".[dev]"
python -m pytest -q
```

--------------------------------

### Run foundation checks (pip install, pytest, ruff)

Source: https://github.com/wfengq/artifactdiff/blob/master/docs/superpowers/plans/2026-08-03-artifactdiff-mvp.md

Commands to install the package in editable mode with dev dependencies, run unit tests for models, normalize, and limits, and run Ruff linting. Expected: all tests pass and no lint errors.

```bash
python -m pip install -e ".[dev]"
```

```bash
python -m pytest tests/unit/test_models.py tests/unit/test_normalize.py tests/unit/test_limits.py -q
```

```bash
python -m ruff check src tests
```

--------------------------------

### Illustrative policy YAML

Source: https://github.com/wfengq/artifactdiff/blob/master/docs/superpowers/specs/2026-08-04-artifactdiff-contract-verification-gate-design.md

Example policy in YAML format showing the canonical structure with schema_version, profile, baseline, expect, allow, protect, visual, and evidence sections. It demonstrates how to specify an expected edit with a selector and operation, and how to configure visual checks and evidence mode.

```yaml
schema_version: "1"
profile: contract-safe

baseline:
  sha256: "..."
  format: docx

expect:
  - id: payment-term
    selector:
      clause: "第四条"
      heading: "付款条件"
      anchor: "发票开具后 30 天内付款"
    operation:
      type: exact_replace
      before: "30 天"
      after: "45 天"
      occurrences: 1

allow:
  - selector:
      clause: "第四条"
    kinds: [modified]

protect:
  - parties
  - money
  - dates
  - headers
  - footers
  - signatures
  - seals
  - attachments

visual:
  explained_regions: pass
  pagination_reflow: review
  protected_region_change: fail
  on_unavailable: review

evidence:
  mode: minimal
```

--------------------------------

### README first screen with quick-start

Source: https://github.com/wfengq/artifactdiff/blob/master/docs/superpowers/plans/2026-08-03-artifactdiff-mvp.md

First screen of the README: title, tagline, and quick-start commands using pipx and the compare command.

```markdown
# ArtifactDiff

Review PDF and Word changes like a code diff - locally, deterministically, and from AI agents.

```bash
pipx install artifactdiff
artifactdiff compare old.pdf new.pdf -o report
```
```

--------------------------------

### Enterprise provider protocols without vendor dependencies

Source: https://github.com/wfengq/artifactdiff/blob/master/docs/superpowers/plans/2026-08-04-contract-plugins-ci-hardening.md

Defines the EnterpriseAttestationProvider and TrustedTimeProvider protocols. Core ships only protocol adapters and a deterministic fake; vendor-specific providers are installed as separate plugins.

```python
class EnterpriseAttestationProvider(Protocol):
    def manifest(self) -> PluginManifest:
        raise NotImplementedError

    def verify(self, attestation: EnterpriseAttestation, expected_payload: bytes) -> None:
        raise NotImplementedError


class TrustedTimeProvider(Protocol):
    def verify(self, evidence: dict[str, JsonValue], signature_digest: str) -> datetime:
        raise NotImplementedError
```

--------------------------------

### Cross-platform CI workflow

Source: https://github.com/wfengq/artifactdiff/blob/master/docs/superpowers/plans/2026-08-03-artifactdiff-mvp.md

Cross-platform CI workflow running on Ubuntu, macOS, and Windows with Python 3.11 and 3.13. Installs the package in editable mode with dev extras, then runs ruff, mypy, and pytest.

```yaml
name: CI
on:
  push:
  pull_request:
jobs:
  test:
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        python-version: ["3.11", "3.13"]
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}
          cache: pip
      - run: python -m pip install -e ".[dev]"
      - run: python -m ruff check src tests scripts
      - run: python -m mypy src/artifactdiff
      - run: python -m pytest -q
```

--------------------------------

### test_end_to_end_pdf_and_docx_reports smoke test

Source: https://github.com/wfengq/artifactdiff/blob/master/docs/superpowers/plans/2026-08-03-artifactdiff-mvp.md

Installed-package smoke test that runs the CLI on demo PDF and DOCX pairs, asserting exit code 0, schema version 1.0, positive total changes, and presence of report.html. Intended to fail initially if the installed workflow is incomplete.

```python
def test_end_to_end_pdf_and_docx_reports(tmp_path: Path) -> None:
    pdf_before, pdf_after = make_demo_pdf_pair(tmp_path)
    docx_before, docx_after = make_demo_docx_pair(tmp_path)
    for name, before, after in [
        ("pdf", pdf_before, pdf_after),
        ("docx", docx_before, docx_after),
    ]:
        response = subprocess.run(
            [sys.executable, "-m", "artifactdiff.cli", "compare", str(before), str(after), "--output", str(tmp_path / name), "--no-visual"],
            capture_output=True, text=True, check=False,
        )
        assert response.returncode == 0, response.stderr
        report = json.loads((tmp_path / name / "report.json").read_text(encoding="utf-8"))
        assert report["schema_version"] == "1.0"
        assert report["summary"]["total_changes"] > 0
        assert (tmp_path / name / "report.html").is_file()
```

--------------------------------

### Run unit tests for contract and adapters

Source: https://github.com/wfengq/artifactdiff/blob/master/docs/superpowers/plans/2026-08-04-contract-ir-foundation.md

Run the unit tests for the contract module and the docx/pdf adapters. Expected to pass with existing adapter ordering and IDs unchanged.

```bash
python -m pytest tests/unit/contract tests/unit/test_docx_adapter.py tests/unit/test_pdf_adapter.py -q
```

--------------------------------

### Run all trust and bundle tests and full suite

Source: https://github.com/wfengq/artifactdiff/blob/master/docs/superpowers/plans/2026-08-04-contract-trust-bundle.md

Runs the full trust, bundle, review, and evidence test suites, then the entire test suite. Both commands are expected to pass all tests.

```bash
python -m pytest tests/unit/trust tests/unit/bundle tests/unit/review tests/unit/evidence tests/integration/session tests/integration/bundle tests/integration/review tests/integration/evidence -q
```

```bash
python -m pytest -q
```

--------------------------------

### Run foundation test suites

Source: https://github.com/wfengq/artifactdiff/blob/master/docs/superpowers/plans/2026-08-04-contract-ir-foundation.md

Commands to run the focused contract and adapter tests first, then the full test suite to ensure all new and existing tests pass.

```bash
python -m pytest tests/unit/contract tests/integration/contract/test_contract_service.py tests/unit/test_docx_adapter.py tests/unit/test_pdf_adapter.py -q
```

```bash
python -m pytest -q
```

--------------------------------

### stable_zip: deterministic ZIP creation for DOCX

Source: https://github.com/wfengq/artifactdiff/blob/master/docs/superpowers/plans/2026-08-04-contract-corpus-release.md

Deterministic ZIP writer used for DOCX output. It sorts entries, uses a fixed timestamp (1980-01-01), sets permissions to 0o600, and uses ZIP_DEFLATED with compresslevel=9 to ensure byte-stable output. Do not use host locale, current time, random IDs, or installed system fonts.

```python
FIXED_ZIP_TIME = (1980, 1, 1, 0, 0, 0)


def stable_zip(source_dir: Path, output: Path) -> None:
    with ZipFile(output, "w", ZIP_DEFLATED, compresslevel=9) as archive:
        for path in sorted(item for item in source_dir.rglob("*") if item.is_file()):
            info = ZipInfo(path.relative_to(source_dir).as_posix(), FIXED_ZIP_TIME)
            info.external_attr = 0o600 << 16
            archive.writestr(info, path.read_bytes(), compress_type=ZIP_DEFLATED, compresslevel=9)
```

--------------------------------

### Run the complete project suite

Source: https://github.com/wfengq/artifactdiff/blob/master/docs/superpowers/plans/2026-08-11-exact-occurrence-alignment.md

Runs the entire test suite. Expected: zero failures.

```powershell
.venv\Scripts\python -m pytest -q
```

--------------------------------

### Corpus manifest case definitions (cases.yaml)

Source: https://github.com/wfengq/artifactdiff/blob/master/docs/superpowers/plans/2026-08-04-contract-corpus-release.md

Example entries from the corpus manifest (cases.yaml). Each case defines an ID, language, path, scenario, mutation, expected outcome, and expected rules. The full manifest covers many scenarios including exact edit, party change, money, currency, date, duration, percentage, clause deletion, page deletion, attachment deletion, header, footer, signature, seal, metadata, pagination reflow, unexplained font/position/image, ambiguous selector, hidden text, tracked revisions, comments, external link, malformed PDF/DOCX, encrypted PDF, ZIP bomb, traversal entry, and symlink escape.

```yaml
- id: zh-docx-docx-exact-payment-edit
  language: zh
  path: docx-docx
  scenario: exact-payment-edit
  mutation: {payment_days: [30, 45]}
  expected_outcome: pass
  expected_rules: [expected.payment-term]
- id: zh-docx-docx-party-change
  language: zh
  path: docx-docx
  scenario: party-change
  mutation: {payment_days: [30, 45], party: [上海示例科技有限公司, 上海其他科技有限公司]}
  expected_outcome: fail
  expected_rules: [contract-safe.protected.parties]
```

--------------------------------

### Run full hardening test suite

Source: https://github.com/wfengq/artifactdiff/blob/master/docs/superpowers/plans/2026-08-04-contract-plugins-ci-hardening.md

Runs the complete plugin, enterprise, CI, and security test suites to verify all hardening changes.

```bash
python -m pytest tests/unit/plugins tests/unit/enterprise tests/unit/ci tests/integration/plugins tests/integration/security tests/integration/enterprise tests/integration/ci -q
```

--------------------------------

### Commit documentation and release readiness

Source: https://github.com/wfengq/artifactdiff/blob/master/docs/superpowers/plans/2026-08-03-artifactdiff-mvp.md

Stages the documentation and release-related files, then commits them with the message 'docs: prepare ArtifactDiff MVP release'. This is the final step before tagging the MVP release.

```bash
git add README.md LICENSE .github/workflows/ci.yml pyproject.toml scripts/create_demo.py tests/integration/test_end_to_end.py src/artifactdiff/cli.py
git commit -m "docs: prepare ArtifactDiff MVP release"
```

--------------------------------

### Run complete interface and full test suites

Source: https://github.com/wfengq/artifactdiff/blob/master/docs/superpowers/plans/2026-08-04-contract-interfaces-review-desk.md

Runs the complete interface test suite and then the full test suite to confirm all tests pass before committing.

```bash
python -m pytest tests/integration/cli tests/integration/mcp tests/integration/review_web tests/integration/reporting tests/integration/test_cli.py tests/integration/test_mcp_server.py tests/integration/test_html_report.py -q
```

```bash
python -m pytest -q
```

--------------------------------

### Run selector, adapter, and analyzer tests

Source: https://github.com/wfengq/artifactdiff/blob/master/docs/superpowers/plans/2026-08-04-contract-ir-foundation.md

Command to run the relevant test suite.

```bash
python -m pytest tests/unit/contract tests/unit/test_docx_adapter.py -q
```

--------------------------------

### Run Rule Suite

Source: https://github.com/wfengq/artifactdiff/blob/master/docs/superpowers/plans/2026-08-04-contract-policy-verdict.md

Command to run unit tests for the verification rule suite.

```bash
python -m pytest tests/unit/verification -q
```

--------------------------------

### Run compatibility tests

Source: https://github.com/wfengq/artifactdiff/blob/master/docs/superpowers/plans/2026-08-04-contract-plugins-ci-hardening.md

Command to run the compatibility and old bundle integration tests, expecting PASS with corrupt versus unsupported distinction.

```bash
python -m pytest tests/unit/test_compatibility.py tests/integration/bundle/test_old_bundle_compatibility.py -q
```

--------------------------------

### FastMCP server with compare_documents tool and stdio main

Source: https://github.com/wfengq/artifactdiff/blob/master/docs/superpowers/plans/2026-08-03-artifactdiff-mvp.md

FastMCP server implementation exposing the compare_documents tool and a stdio main entry point. The tool validates absolute paths, computes a bounded comparison response, and returns an error contract on ArtifactDiffError.

```python
mcp = FastMCP("ArtifactDiff")


@mcp.tool(name="compare_documents")
async def compare_documents_tool(
    before_path: str,
    after_path: str,
    output_dir: str | None = None,
    visual: bool = True,
    force: bool = False,
) -> dict[str, object]:
    try:
        before = validate_source(Path(before_path), force=force, require_absolute=True)
        after = validate_source(Path(after_path), force=force, require_absolute=True)
        destination = _absolute_output_dir(output_dir, before, after)
        run = compare_documents(before, after, destination, options=CompareOptions(visual=visual, force=force))
        return _bounded_comparison_response(run)
    except ArtifactDiffError as error:
        return {"ok": False, "error_type": type(error).__name__, "error": str(error)}


def main() -> None:
    mcp.run(transport="stdio")
```

--------------------------------

### Run DOCX adapter test

Source: https://github.com/wfengq/artifactdiff/blob/master/docs/superpowers/plans/2026-08-03-artifactdiff-mvp.md

Runs the DOCX adapter unit test. Expected to fail initially because the artifactdiff.formats.docx module does not exist yet.

```bash
python -m pytest tests/unit/test_docx_adapter.py -q
```

--------------------------------

### Run review web integration tests

Source: https://github.com/wfengq/artifactdiff/blob/master/docs/superpowers/plans/2026-08-04-contract-interfaces-review-desk.md

Command to run the integration tests for the review web module. Expected to pass for canonical equivalence, XSS strings, review pagination, approval, fail refusal, key non-exposure, and all view states.

```bash
python -m pytest tests/integration/review_web -q
```

--------------------------------

### Run full verification suite

Source: https://github.com/wfengq/artifactdiff/blob/master/docs/superpowers/plans/2026-08-03-artifactdiff-mvp.md

Complete automated verification commands: lint, type check, tests, package build, and demo generation. Expected to pass and produce both demo reports.

```bash
python -m ruff check src tests scripts
```

```bash
python -m mypy src/artifactdiff
```

```bash
python -m pytest -q
```

```bash
python -m build
```

```bash
python scripts/create_demo.py --output demo-output
```

--------------------------------

### artifactdiff CLI help and review commands

Source: https://github.com/wfengq/artifactdiff/blob/master/README.md

CLI commands for the artifactdiff interface: general help, policy help, verify help, and reviewing a bundle at a given path. The CLI can create/validate/seal policies, open controlled sessions, verify changes, inspect findings, approve findings, and verify or pack bundles.

```console
artifactdiff --help
artifactdiff policy --help
artifactdiff verify --help
artifactdiff review path/to/review-bundle
```

--------------------------------

### Run signature vectors and commit

Source: https://github.com/wfengq/artifactdiff/blob/master/docs/superpowers/plans/2026-08-04-contract-trust-bundle.md

Runs the unit tests for the trust module and commits the changes with a descriptive message.

```bash
python -m pytest tests/unit/trust -q
```

```bash
git add pyproject.toml src/artifactdiff/errors.py src/artifactdiff/trust tests/unit/trust
git commit -m "feat: add offline Ed25519 trust"
```

--------------------------------

### Run service test for hash fast path

Source: https://github.com/wfengq/artifactdiff/blob/master/docs/superpowers/plans/2026-08-03-artifactdiff-mvp.md

Run the service test for the hash fast path. Expected to fail because the 'artifactdiff.service' module does not exist yet.

```bash
python -m pytest tests/integration/test_service.py::test_compare_documents_uses_hash_fast_path -q
```

--------------------------------

### Run all tests

Source: https://github.com/wfengq/artifactdiff/blob/master/docs/superpowers/plans/2026-08-04-contract-plugins-ci-hardening.md

Executes the entire test suite to confirm everything passes.

```bash
python -m pytest -q
```

--------------------------------

### Run CLI integration tests

Source: https://github.com/wfengq/artifactdiff/blob/master/docs/superpowers/plans/2026-08-03-artifactdiff-mvp.md

Runs the CLI integration tests. Expected to fail because artifactdiff.cli does not exist yet.

```bash
python -m pytest tests/integration/test_cli.py -q
```

--------------------------------

### LibreOffice discovery and conversion tests

Source: https://github.com/wfengq/artifactdiff/blob/master/docs/superpowers/plans/2026-08-03-artifactdiff-mvp.md

Tests LibreOffice discovery and conversion. The first test verifies that the ARTIFACTDIFF_LIBREOFFICE environment variable is preferred. The second test mocks subprocess.run to verify the conversion command uses an argument array and returns the expected PDF path.

```python
def test_find_libreoffice_prefers_explicit_environment(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
    executable = tmp_path / "soffice.exe"
    executable.write_bytes(b"")
    monkeypatch.setenv("ARTIFACTDIFF_LIBREOFFICE", str(executable))
    assert find_libreoffice() == executable.resolve()
```

```python
def test_conversion_uses_argument_array(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
    calls: list[list[str]] = []
    monkeypatch.setattr(subprocess, "run", lambda args, **kwargs: calls.append(args) or CompletedProcess(args, 0, "", ""))
    source = tmp_path / "input.docx"
    source.write_bytes(b"fixture")
    expected = tmp_path / "out" / "input.pdf"
    expected.parent.mkdir()
    expected.write_bytes(b"%PDF")
    assert convert_docx_to_pdf(source, expected.parent, tmp_path / "soffice") == expected
    assert calls[0][0] == str(tmp_path / "soffice")
```

--------------------------------

### Run visual tests to verify failure

Source: https://github.com/wfengq/artifactdiff/blob/master/docs/superpowers/plans/2026-08-03-artifactdiff-mvp.md

Runs the visual unit tests; expected to fail because the artifactdiff.visual module does not exist yet.

```bash
python -m pytest tests/unit/test_visual.py -q
```

--------------------------------

### Command: run direct alignment tests

Source: https://github.com/wfengq/artifactdiff/blob/master/docs/superpowers/plans/2026-08-11-exact-occurrence-alignment.md

Runs the direct tests to verify expected import RED. Expected: collection error only because artifactdiff.verification.alignment does not exist.

```powershell
.venv\Scripts\python -m pytest tests/unit/verification/test_alignment.py -q
```

--------------------------------

### Run golden gate (first run)

Source: https://github.com/wfengq/artifactdiff/blob/master/docs/superpowers/plans/2026-08-04-contract-corpus-release.md

Run the golden gate script with the manifest and corpus to produce the first results file.

```bash
python scripts/run_golden_gate.py --manifest corpus/cases.yaml --corpus corpus/generated --output build/golden-results-1.json
```

--------------------------------

### load_contract service function

Source: https://github.com/wfengq/artifactdiff/blob/master/docs/superpowers/plans/2026-08-04-contract-ir-foundation.md

Loads a contract from a path by validating the source, obtaining an adapter, loading a snapshot, and analyzing it to produce a contract document. Returns a tuple of the snapshot and contract document.

```python
def load_contract(path: Path, *, render: bool, force: bool, workdir: Path) -> tuple[DocumentSnapshot, ContractDocument]:
    source = validate_source(path, force=force)
    snapshot = adapter_for(source).load(source, render=render, workdir=workdir, force=force)
    return snapshot, analyze_contract(snapshot)
```

--------------------------------

### ArtifactDiff CLI Commands for Contract Workflows

Source: https://github.com/wfengq/artifactdiff/blob/master/docs/superpowers/specs/2026-08-04-artifactdiff-contract-verification-gate-design.md

Shows the new command-line interface entries for policy creation, validation, sealing, session opening, verification, reviewing, approving, and bundling operations. All commands support machine-readable JSON where appropriate; human status goes to stdout, public errors to stderr, and expected domain failures avoid tracebacks by default.

```shell
artifactdiff policy create BASELINE -o POLICY
artifactdiff policy validate BASELINE POLICY
artifactdiff policy seal BASELINE POLICY [--sign IDENTITY] -o SEALED_POLICY
artifactdiff session open BASELINE --policy SIGNED_POLICY --output SESSION
artifactdiff verify BASELINE CANDIDATE --policy SEALED_POLICY [--session SESSION] --output BUNDLE
artifactdiff review BUNDLE
artifactdiff approve BUNDLE --finding ID --reason TEXT --sign IDENTITY
artifactdiff bundle verify BUNDLE
artifactdiff bundle pack BUNDLE --mode sealed --recipient PUBLIC_KEY
```