Validation and reports

validate-project-structure is the deterministic gate for generated and hand-written ContractForge projects. It validates project shape and can ask installed adapters to plan the contracts without executing platform code.

Validate a project folder

contractforge-ai validate-project-structure generated/supabase \
  --adapter databricks \
  --adapter aws \
  --format html > generated/supabase/project_validation.html

The validator checks:

• project.yaml;
• referenced environment YAMLs;
• referenced shared connection YAMLs;
• ingestion bundles and sibling annotations/operations/access files;
• connection inheritance and ingestion-level overrides;
• project schedule cron and timezone;
• adapter planner status, warnings and blockers.

Output formats

Format	Use
text	Local terminal checks.
json	CI gates and automation.
markdown	Pull-request comments.
html	Human review, screenshots and project handoff.

HTML is the preferred review format because real projects have long paths, adapter warning codes and planner payloads. The report renders findings and adapter evidence as cards instead of forcing them into narrow table columns.

Status mapping

Status	Ready	Meaning
READY	true	No deterministic blockers or adapter warnings.
READY_WITH_WARNINGS	true	Only reviewable warnings remain.
NEEDS_DECISIONS	false	Human decisions remain before deploy.
INVALID	false	Project structure, bundle loading or adapter planning failed.
UNSAFE	false	Inline secrets or unsafe project inputs were found.

Adapter warnings do not become silent success. They remain visible in the report, but warning-only projects remain ready=true.

Adapter-aware validation

Adapter-aware validation calls public planning APIs only:

Adapter	Planner
Databricks	plan_databricks_contract
AWS	plan_aws_contract

It does not:

• create Databricks jobs;
• call AWS Glue APIs;
• deploy infrastructure;
• execute ingestion;
• resolve secret values.

Real examples

Validate the USGS REST/GeoJSON project:

contractforge-ai validate-project-structure examples/real-world/usgs-earthquake-rest-medallion \
  --adapter databricks \
  --adapter aws \
  --format html > usgs-project-validation.html

Validate the Supabase JDBC medallion project:

contractforge-ai validate-project-structure examples/real-world/supabase-jdbc-medallion \
  --adapter databricks \
  --adapter aws \
  --format html > supabase-project-validation.html

Expected interpretation:

• Databricks contracts should plan as supported when the semantics are within the Databricks adapter surface.
• AWS contracts may plan as SUPPORTED_WITH_WARNINGS when semantics are supported but need production review, such as Spark SQL expression quality or Iceberg hash-diff performance.
• The project can be READY_WITH_WARNINGS when there are no critical or high findings.

Provider output cannot override validation

If a provider says "ready" while deterministic validation says NEEDS_DECISIONS, INVALID or UNSAFE, the provider output is wrong. The validator remains authoritative.

Use validate-artifact for generated model output:

contractforge-ai validate-artifact \
  --model-output provider-output.json \
  --prompt project.spec.enrichment.v1 \
  --fallback deterministic-spec.json \
  --format html > provider_validation.html