visioncraft 0.3.0

Explicit quality plans, bounded execution receipts and deterministic evidence gates
Documentation

VisionCraft

Engineering guidance and executable evidence gates for coding agents and people.

VisionCraft helps you define a change, test it and give reviewers a clear record of what the results support. Use its coding-agent skill, Rust library or CLI with your existing repository, CI and issue tracker.

For an empty-search bug, that might mean reproducing the error, fixing it and checking both empty and ordinary queries. A shared event-format change needs consumer, compatibility and migration checks too. The method scales with the consequences, while keeping a merged fix distinct from a deployed one.

Component What it provides
Skill Expectation-driven development, TDD, debugging, architecture decisions and review practices
Rust core Typed plans, evidence verification and deterministic gate decisions; no process or network calls
CLI Explicit command execution, bounded captures and source/evidence freshness checks

Required missing, failed, stale or incomplete evidence cannot earn a pass. Passing means the declared checks satisfied their policy; it does not establish complete coverage, correctness, security or deployment. No Agentbox installation, agent framework or model subscription is required for the core.

Crates.io · Rust API · VisionFlow estate

Install

Rust 1.88 or later is required. Native execution currently supports Linux with glibc or musl; the deterministic library remains independent of the operating system.

cargo install visioncraft --locked --version 0.3.0
visioncraft --help

For the pure Rust library without CLI/process dependencies:

[dependencies]
visioncraft = { version = "0.3.0", default-features = false }

For a coding agent, install the complete skills/visioncraft/ directory from the same release using your harness's skill mechanism. Keep its references/ and assets/ alongside SKILL.md; they contain the actual engineering method.

A complete local example

Create a small Git repository with a real assertion. The input list explicitly includes the files whose bytes the check claims to cover.

mkdir visioncraft-example
cd visioncraft-example
git init -q
printf '12\n' > limit.txt
git add limit.txt
git -c user.name=Example -c user.email=example@example.invalid commit -qm baseline

visioncraft plan init --out quality.json --input limit.txt \
  --configuration 'POSIX assertion of configured limit' \
  -- sh -c 'test "$(cat limit.txt)" = 12'
visioncraft plan check quality.json --json
visioncraft run quality.json --all --out evidence-1
visioncraft evaluate quality.json --receipts evidence-1 --json

run captures execution; evaluate verifies the plan, source and capture hashes, invocation and exit status. Commands use argument arrays without an implicit shell; this example explicitly requests sh -c.

Change limit.txt and repeat evaluate: the old receipt no longer satisfies the input. After intentionally changing scope or configuration, create a new plan and run directory. Existing output paths are refused.

Include relevant source, lockfiles and configuration in --input. Only environment variables named through --env are inherited. Set --timeout-ms and --max-output-bytes; aggregate limits are 1,024 checks, one day of declared deadlines and one GiB of capture per plan.

Repository/configuration labels are caller declarations, reported as plan-declared-unverified. To attest current labels, supply a Subject record:

visioncraft evaluate quality.json --receipts evidence-1 \
  --current-subject current-subject.json --json

Its source fields are checked against disk; matching repository/configuration labels remain caller-attested. A digest written in a label does not verify a file: include the actual configuration in --input to bind its bytes.

Expectations and review

The EDD reference explains how to bind expectations to checks, positive controls, regression tests and independent review requirements.

visioncraft expectations check quality.json --receipts evidence-1 --json
visioncraft gate evaluate quality.json --receipts evidence-1 --json

Both assess the entire required gate, including checks not referenced by an expectation. Optional failures stay visible. Actual test or line coverage remains unknown unless an observer supplies it.

For imported findings, VisionCraft uses Sealmap's receipt contract:

sealmap review init findings.json --out finding-receipts.json
# Add actual reproductions and dispositions, preserving the original findings.
sealmap review check finding-receipts.json --json
sealmap review summary finding-receipts.json

These checks establish structure and byte identity; an auditor judges whether the observations support the findings.

Specialist upstreams

Deepsec is an optional, independently installed security reviewer with a versioned adapter contract.

# Inspect the resolved plan without running a reviewer.
visioncraft deepsec --diff origin/main --dry-run
# Run the explicitly requested review using already configured local credentials.
visioncraft deepsec --diff origin/main
# Candidate discovery only; SCANNED is not a completed review.
visioncraft deepsec --scan-only

The adapter freezes file selection, checks source bytes before and after, and requires fresh analysis evidence. Staged mode refuses differing index and working-tree bytes. Empty exports, refusals, partial reviews and unsupported versions cannot pass. Full mode covers the scanner's pending candidates, not the whole program; historical findings may remain in threshold assessment. See the integration guide for scope, routes and spend controls, and maintenance procedure for qualifying upgrades.

Agentic QE supplies optional test and coverage tools through its own CLI/MCP surface. Follow its worked integration and result contract. Inspect and execute generated tests in the project; keep measured coverage distinct from estimates and retain insufficient-evidence results.

Reading the skill does not install, authenticate or activate either service.

Architecture records and diagrams

Keep decisions and diagrams in the project's existing corpus, linked to requirements, inspected commits, governed source paths and release observations. Rendering a diagram does not verify its claims.

See decision guidance, diagram diagnosis, traceability and this project's verified ADRs and diagrams.

Rust library

The core accepts typed data and supplied bytes. It does not trust an artifact because its filename or claimed hash looks plausible:

use visioncraft::{Artifact, VerifiedArtifacts};

let bytes = b"actual check output\n";
let artifact = Artifact {
    path: "attempt/stdout.log".into(),
    sha256: visioncraft::sha256(bytes),
};
let mut verified = VerifiedArtifacts::default();
verified.insert(&artifact, bytes)?;
assert!(verified.contains(&artifact));
# Ok::<(), visioncraft::ContractError>(())

QualityPlan, ExecutionReceipt and EvaluationContext describe the policy, observations and verified current inputs. evaluate returns both the aggregate outcome and individual check/expectation results. See the generated rustdoc and executable contract tests for complete typed examples.

Place in the VisionFlow estate

VisionCraft succeeds the Build with Quality skill developed across DreamLab-AI's estate. The migration guide accounts for every former resource. It remains independently usable.

Project Connection
VisionFlow Cross-project architecture, audit records and documentation
Sealmap Shared diagram, review and model-family contracts consumed by VisionCraft
Agentbox Installs a pinned release and canonical skill, supplies host policy and credentials, and routes agents through Jev

Agentbox's Deepsec adapter projects policy into the same VisionCraft executable; it retains no parallel gate implementation. Ruflo handles coordination and Agentic QE provides direct testing tools. A source pin does not establish live activation. The Agentbox integration reference tracks memory, routing and deployment responsibilities.

Limits and development

The process runner is not a sandbox. Children retain the caller's filesystem and network authority; environment filtering is not secret isolation. Linux process groups support cancellation and deadlines, but a deliberately escaping process or a blocked kernel filesystem call needs host-level containment. Private capture directories protect ordinary local handling, not a hostile concurrent filesystem. Keep source-bearing evidence out of public commits. Linux can recognise exited zombie group members through an unrestricted /proc view; hidden, unreadable or uncertain state remains non-passing. Native execution on other platforms returns unsupported before spawning a child. Process-wide child reapers must not compete with the runner's ownership of its children.

Run cargo test, cargo clippy --all-targets -- -D warnings, cargo fmt --check and RUSTDOCFLAGS='-D warnings' cargo doc --no-deps. The implementation contract records acceptance boundaries. The release review records reproduced counterexamples and their dispositions. See evaluation evidence for the bounded comparison; no measured success-rate improvement is claimed.

MIT OR Apache-2.0. Attributed BeautifulRust material retains its original MIT notice. See provenance, MIT and Apache-2.0.