W
Wrkr

Contracts and Schemas

Contracts and Schemas

Scan Governance Additions

wrkr scan --json includes additive governance-first artifacts while preserving existing raw finding and inventory surfaces.

  • control_backlog.control_backlog_version = "1" identifies the backlog schema.
  • control_backlog.items[*].signal_class is one of unique_wrkr_signal or supporting_security_signal.
  • control_backlog.items[*].recommended_action is one of attach_evidence, approve, remediate, downgrade, deprecate, exclude, monitor, inventory_review, suppress, or debug_only.
  • control_backlog.items[*].confidence is one of high, medium, or low.
  • control_backlog.items[*].linked_control_path_node_ids / linked_control_path_edge_ids are additive graph join keys tied to the versioned control_path_graph.
  • agent_privilege_map[*].credential_provenance and action_paths[*].credential_provenance use stable enums: static_secret, workload_identity, inherited_human, oauth_delegation, jit, and unknown.
  • control_path_graph.version = "1" identifies the additive governance graph schema in saved state, report JSON, and evidence bundles.
  • control_backlog.items[*].write_path_classes may include read, write, pr_write, repo_write, release_write, package_publish, deploy_write, infra_write, secret_bearing_execution, and production_adjacent_write.
  • control_backlog.items[*].governance_controls[*].control is one of owner_assigned, approval_recorded, least_privilege_verified, rotation_evidence_attached, deployment_gate_present, production_access_classified, proof_artifact_generated, or review_cadence_set; status is satisfied, gap, or not_applicable.
  • Governance backlog visibility may use known_approved, known_unapproved, unknown_to_security, accepted_risk, deprecated, revoked, or needs_review. Legacy inventory surfaces still accept the historic approved compatibility value.
  • scan_quality.scan_quality_version = "1" identifies the scan-quality appendix schema.
  • scan_quality.mode is one of quick, governance, or deep.
  • scan_quality.parse_errors[*].recommended_action is suppress for generated/package-manager noise and debug_only for parser diagnostics that should stay outside the active governance backlog.

These fields are additive. Consumers that depend on findings, ranked_findings, top_findings, inventory, profile, posture_score, and compliance_summary can continue to read those fields unchanged.

Secret-bearing workflow semantics are also additive. Workflow references such as ${{ secrets.NAME }} are classified as secret_reference_detected and may combine with secret_used_by_write_capable_workflow; they must not be treated as secret_value_detected unless a detector explicitly proves a value was exposed.

Evidence-state contract model

Wrkr's public report, backlog, risk, and evidence contracts now lead with evidence-scoped control posture.

  • control_resolution_state is one of detected_control, declared_control, external_control_reference, no_visible_control, not_applicable, or contradictory_control.
  • Canonical approval_evidence_state, owner_evidence_state, proof_evidence_state, runtime_evidence_state, target_evidence_state, and credential_evidence_state are one of verified, declared, inferred, unknown, or contradictory.
  • target_class is one of production_impacting, release_adjacent, customer_data_adjacent, internal_tooling, developer_productivity, test_demo_sandbox, or unknown.
  • action_path_type is one of ai_assisted_workflow, agent_framework, automation_bot, ci_cd_workflow, legacy_script, plain_source_code, or unknown_executable_path.
  • Coverage-qualified absence surfaces use not_found_with_complete_coverage, not_found_with_reduced_coverage, not_scanned, unsupported_surface, or candidate_parse_failed.
  • Runtime absence surfaces use not_collected, not_applicable, missing_required, or missing_for_control_claim.

Compatibility aliases such as missing_approval_paths, missing_policy_paths, missing_proof_paths, and older approval_gap surfaces remain additive compatibility shims in v1, but they are derived from the canonical evidence-state projection rather than serving as independent truth.

Enterprise Evidence Contracts

Wrkr's Sprint 2 enterprise-evidence surface stays local-file based and deterministic.

  • schemas/v1/evidence/external-control-evidence.schema.json is the public v1 sidecar contract for imported ownership, approval, branch protection, deployment approvals, required checks, freeze windows, kill switches, and other external control evidence.
  • wrkr-control-declarations.yaml and .wrkr/control-declarations.yaml are versioned declaration inputs for owner mappings, target classes, non-production declarations, and declared control links.
  • action_paths[*].evidence_decisions[] and agent_action_bom.items[*].evidence_decisions[] preserve source precedence, freshness, selected evidence, and rejected lower-precedence candidates instead of flattening imported evidence to one opaque winner.
  • action_paths[*].contradictions[], closure_requirements, lifecycle_queue, and evidence_completeness keep enterprise conflicts, required closure evidence, lifecycle ownership gaps, and sufficiency scoring explicit across report, BOM, and risk surfaces.
  • Accepted governance dispositions stay auditable: accepted_risk and suppression metadata remain visible in JSON/report artifacts instead of deleting evidence.
  • Evidence completeness is not risk scoring. Low evidence_completeness means Wrkr needs more evidence for the current conclusion, not that the path is safe.
  • Canonical source precedence is documented and deterministic: provider export, signed declaration, repo-local policy/config, app catalog ownership, git/review inference, then naming-convention or repo fallback.
  • agent_action_bom.summary.primary_view is the focused workflow-BOM contract for Sprint 3 buyer output. It carries the selected path_id, selection reason, path map, evidence/control posture, governed-path before/after view, and appendix refs without removing the full agent_action_bom.items[*] detail surface.

Canonical references

  • Root exit codes and flags: docs/commands/root.md
  • Command contract index: docs/commands/index.md
  • Manifest open specification: docs/specs/wrkr-manifest.md
  • JSON schemas: schemas/v1/
    • schemas/v1/control-path-graph.schema.json

Command anchors

wrkr manifest generate --json
wrkr export --format inventory --json
wrkr verify --chain --json

Compatibility posture

Within the same major contract line, additive fields are expected to remain backward compatible for consumers that ignore unknown optional fields. Command-specific validators may still reject inputs that never matched the documented contract, for example non-scan JSON passed to wrkr campaign aggregate.

Drift-review contract model

Wrkr's recurring drift-review surface is baseline-backed and fail-closed by design.

  • schemas/v1/regress/regress-baseline.schema.json now carries additive action_paths_captured and normalized action_paths[] state so wrkr regress can compare stable workflow/action-path posture across reruns.
  • schemas/v1/regress/regress-result.schema.json now carries additive comparison_status, comparison_issues[], drift_category_count, and drift_categories[] with stable categories such as new_write_paths, new_deploy_paths, new_credentials, new_unknown_approval_evidence, resolved_gaps, worsened_paths, new_contradictions, paths_ready_for_control, removed_paths, changed_authority, changed_evidence, and changed_target_class.
  • summary.regress_drift mirrors the same additive drift-category model inside wrkr report --json and report evidence artifacts.
  • agent_action_bom.summary.drift_review mirrors the same additive drift-category model inside buyer-facing workflow-first report output.
  • assessment-manifest.json stage metadata now carries additive comparison_status and drift_category_count on stages.regress so repeatable assessment workflows can distinguish clean drift review from unavailable baseline comparison data.

Q&A

Where are Wrkr JSON schemas and contracts defined?

Schemas live in schemas/v1/, while command and flag contracts are documented under docs/commands/.

Which spec defines the Wrkr manifest contract?

docs/specs/wrkr-manifest.md is the canonical manifest specification reference.

How should I design consumers to remain compatible over time?

Treat additive optional fields as non-breaking, validate required fields strictly, and pin expected schema/manifest versions in CI checks.

Which JSON artifacts are valid inputs to wrkr campaign aggregate?

Only complete wrkr scan --json artifacts. Other status=ok envelopes from commands such as wrkr version or wrkr report are not valid campaign inputs.