whetstone_RSA/semantic/rsa_gate_extraction_contracts_v0.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "whetstone-rsa/gate-extraction-contracts-v0",
  "title": "RSA Gate Extraction Contracts V0",
  "version": "0.1.0-bootstrap",
  "status": "bootstrap_source_of_truth",
  "notes": [
    "This file defines machine-readable extraction contracts for mining RSA-aligned gate rows from surviving whetstone_DSL artifacts.",
    "Contracts are gate-native rather than taskitem-native.",
    "This artifact records what context may be used, what labels are valid, how provenance should be tagged, and when a candidate row must be rejected."
  ],
  "enums": {
    "provenance_class": [
      "direct_explicit",
      "direct_bundled",
      "reconstructed",
      "untrusted"
    ],
    "label_shape": [
      "enum",
      "factorized_boolean_slots",
      "ordered_string_list"
    ],
    "artifact_role": [
      "primary_context",
      "primary_label_source",
      "supporting_context",
      "audit_only"
    ]
  },
  "entities": {
    "ExtractionContract": {
      "purpose": "Defines how one RSA gate should be extracted from historical artifacts.",
      "fields": [
        {
          "name": "gate_id",
          "type": "string",
          "required": true
        },
        {
          "name": "status",
          "type": "string",
          "required": true
        },
        {
          "name": "source_artifacts",
          "type": "array<object>",
          "required": true
        },
        {
          "name": "source_fields",
          "type": "object",
          "required": true
        },
        {
          "name": "allowed_context_fields",
          "type": "array<string>",
          "required": true
        },
        {
          "name": "forbidden_context_fields",
          "type": "array<string>",
          "required": true
        },
        {
          "name": "label_shape",
          "type": "enum:label_shape",
          "required": true
        },
        {
          "name": "label_schema",
          "type": "object",
          "required": true
        },
        {
          "name": "default_provenance",
          "type": "enum:provenance_class",
          "required": true
        },
        {
          "name": "rejection_rules",
          "type": "array<string>",
          "required": true
        },
        {
          "name": "blocking_issue",
          "type": "string",
          "required": false
        }
      ]
    }
  },
  "global_rules": {
    "row_fields": [
      "gate_id",
      "decision_context",
      "decision_label",
      "decision_provenance",
      "source_artifacts",
      "rejection_flags"
    ],
    "reject_when": [
      "candidate label depends on downstream execution results",
      "candidate label is inferred only from post-hoc failure or success",
      "candidate label shape does not match the RSA gate contract",
      "required pre-decision context is missing",
      "artifact mixes unrelated tasks without isolatable per-task context"
    ]
  },
  "contracts": {
    "prereq_op_selector": {
      "status": "first_pass_extractable",
      "source_artifacts": [
        {
          "path_glob": "CLionProjects/whetstone_DSL/logs/taskitem_runs/*/01_intake.json",
          "role": "primary_context"
        },
        {
          "path_glob": "CLionProjects/whetstone_DSL/logs/taskitem_runs/*/02_generate_taskitems.json",
          "role": "primary_label_source"
        },
        {
          "path_glob": "CLionProjects/whetstone_DSL/logs/taskitem_runs/*/04_validate_taskitem.json",
          "role": "audit_only"
        }
      ],
      "source_fields": {
        "context_fields": [
          "01_intake.json.normalizedRequirements",
          "01_intake.json.parsedSpec",
          "01_intake.json.conflictSignals",
          "01_intake.json.ambiguitySignals",
          "02_generate_taskitems.json.tasks[*].title",
          "02_generate_taskitems.json.tasks[*].milestoneId",
          "02_generate_taskitems.json.tasks[*].dependencyTaskIds",
          "02_generate_taskitems.json.tasks[*].confidence",
          "02_generate_taskitems.json.tasks[*].ambiguityCount",
          "02_generate_taskitems.json.tasks[*].reasons"
        ],
        "label_fields": [
          "02_generate_taskitems.json.tasks[*].prerequisiteOps"
        ]
      },
      "allowed_context_fields": [
        "task title",
        "local task intent",
        "dependency ids",
        "local ambiguity signals",
        "local conflict signals",
        "normalized requirements",
        "milestone grouping"
      ],
      "forbidden_context_fields": [
        "acceptance commands",
        "target files",
        "required tools",
        "downstream execution results",
        "validation pass/fail outcome",
        "generated code"
      ],
      "label_shape": "factorized_boolean_slots",
      "label_schema": {
        "slots": [
          {
            "name": "needs_validate_intake",
            "source_value": "validate-intake",
            "type": "boolean"
          },
          {
            "name": "needs_architect_review",
            "source_value": "architect-review",
            "type": "boolean"
          },
          {
            "name": "needs_resolve_dependencies",
            "source_value": "resolve-dependencies",
            "type": "boolean"
          }
        ],
        "accepted_source_values": [
          "validate-intake",
          "architect-review",
          "resolve-dependencies"
        ]
      },
      "default_provenance": "direct_bundled",
      "rejection_rules": [
        "prerequisiteOps contains values outside the accepted slot vocabulary",
        "task cannot be isolated from sibling tasks in the artifact",
        "confidence or dependency signals are missing and context becomes too thin",
        "list appears post-processed rather than source-emitted"
      ]
    },
    "target_file_selection": {
      "status": "first_pass_extractable",
      "source_artifacts": [
        {
          "path_glob": "CLionProjects/whetstone_DSL/logs/taskitem_runs/*/01_intake.json",
          "role": "primary_context"
        },
        {
          "path_glob": "CLionProjects/whetstone_DSL/logs/taskitem_runs/*/02_generate_taskitems.json",
          "role": "primary_label_source"
        },
        {
          "path_glob": "CLionProjects/whetstone_DSL/datasets/example_run_specs/*",
          "role": "supporting_context"
        }
      ],
      "source_fields": {
        "context_fields": [
          "01_intake.json.normalizedRequirements",
          "01_intake.json.parsedSpec",
          "02_generate_taskitems.json.tasks[*].title",
          "02_generate_taskitems.json.tasks[*].milestoneId",
          "02_generate_taskitems.json.tasks[*].dependencyTaskIds",
          "02_generate_taskitems.json.tasks[*].reasons"
        ],
        "label_fields": [
          "02_generate_taskitems.json.tasks[*].executionContract.targetFiles"
        ]
      },
      "allowed_context_fields": [
        "task title",
        "local task intent",
        "relevant normalized requirements",
        "milestone grouping",
        "dependency ids",
        "scenario family metadata"
      ],
      "forbidden_context_fields": [
        "acceptance commands",
        "required tools",
        "execution specificity score",
        "validation diagnostics",
        "downstream worker assignment",
        "final implementation output"
      ],
      "label_shape": "ordered_string_list",
      "label_schema": {
        "field": "target_files",
        "item_type": "repo_path",
        "ordered": true,
        "non_empty": true
      },
      "default_provenance": "direct_bundled",
      "rejection_rules": [
        "targetFiles list is empty",
        "targetFiles include unrelated repository surfaces not justified by task text",
        "targetFiles appear copied across all sibling tasks without local variation",
        "targetFiles depend on downstream implementation or validation feedback"
      ]
    },
    "acceptance_command_selection": {
      "status": "first_pass_extractable_with_review",
      "source_artifacts": [
        {
          "path_glob": "CLionProjects/whetstone_DSL/logs/taskitem_runs/*/01_intake.json",
          "role": "primary_context"
        },
        {
          "path_glob": "CLionProjects/whetstone_DSL/logs/taskitem_runs/*/02_generate_taskitems.json",
          "role": "primary_label_source"
        },
        {
          "path_glob": "CLionProjects/whetstone_DSL/logs/taskitem_runs/*/04_validate_taskitem.json",
          "role": "audit_only"
        }
      ],
      "source_fields": {
        "context_fields": [
          "01_intake.json.normalizedRequirements",
          "02_generate_taskitems.json.tasks[*].title",
          "02_generate_taskitems.json.tasks[*].milestoneId",
          "02_generate_taskitems.json.tasks[*].executionContract.targetFiles"
        ],
        "label_fields": [
          "02_generate_taskitems.json.tasks[*].executionContract.acceptanceCommands"
        ]
      },
      "allowed_context_fields": [
        "task title",
        "local task intent",
        "target files",
        "normalized requirements that imply verification surface"
      ],
      "forbidden_context_fields": [
        "validation outcome",
        "execution success or failure",
        "downstream generated code",
        "execution specificity score used as a target proxy"
      ],
      "label_shape": "ordered_string_list",
      "label_schema": {
        "field": "acceptance_commands",
        "item_type": "command_id",
        "ordered": true,
        "non_empty": true
      },
      "default_provenance": "direct_bundled",
      "rejection_rules": [
        "acceptanceCommands are obvious template defaults unrelated to task surface",
        "acceptanceCommands require information only known after code edits",
        "acceptanceCommands are inconsistent with target files or implied verification surface"
      ]
    },
    "required_tool_selection": {
      "status": "first_pass_extractable_with_review",
      "source_artifacts": [
        {
          "path_glob": "CLionProjects/whetstone_DSL/logs/taskitem_runs/*/01_intake.json",
          "role": "primary_context"
        },
        {
          "path_glob": "CLionProjects/whetstone_DSL/logs/taskitem_runs/*/02_generate_taskitems.json",
          "role": "primary_label_source"
        },
        {
          "path_glob": "CLionProjects/whetstone_DSL/logs/taskitem_runs/*/04_validate_taskitem.json",
          "role": "audit_only"
        }
      ],
      "source_fields": {
        "context_fields": [
          "01_intake.json.normalizedRequirements",
          "02_generate_taskitems.json.tasks[*].title",
          "02_generate_taskitems.json.tasks[*].prerequisiteOps",
          "02_generate_taskitems.json.tasks[*].executionContract.targetFiles"
        ],
        "label_fields": [
          "02_generate_taskitems.json.tasks[*].executionContract.requiredTools"
        ]
      },
      "allowed_context_fields": [
        "task title",
        "local task intent",
        "prerequisite ops",
        "target files",
        "normalized requirements"
      ],
      "forbidden_context_fields": [
        "validation-recommended tools as label source",
        "downstream execution traces",
        "final worker selection"
      ],
      "label_shape": "ordered_string_list",
      "label_schema": {
        "field": "required_tools",
        "item_type": "tool_id",
        "ordered": true,
        "non_empty": true
      },
      "default_provenance": "direct_bundled",
      "rejection_rules": [
        "requiredTools are clearly framework boilerplate with no task-local variation",
        "requiredTools include post-hoc validator recommendations instead of generation-time selections",
        "requiredTools cannot be mapped to a stable tool registry"
      ]
    },
    "verification_type": {
      "status": "second_pass_reconstruction_target",
      "source_artifacts": [
        {
          "path_glob": "CLionProjects/whetstone_DSL/logs/taskitem_runs/*/02_generate_taskitems.json",
          "role": "supporting_context"
        }
      ],
      "source_fields": {
        "context_fields": [
          "02_generate_taskitems.json.tasks[*].title",
          "02_generate_taskitems.json.tasks[*].executionContract.targetFiles",
          "02_generate_taskitems.json.tasks[*].executionContract.acceptanceCommands"
        ],
        "label_fields": []
      },
      "allowed_context_fields": [
        "target files",
        "acceptance commands",
        "task title",
        "normalized requirements"
      ],
      "forbidden_context_fields": [
        "downstream validation outcome",
        "downstream execution result"
      ],
      "label_shape": "enum",
      "label_schema": {
        "accepted_values": [
          "unit",
          "schema",
          "docs",
          "smoke"
        ]
      },
      "default_provenance": "reconstructed",
      "rejection_rules": [
        "verification type cannot be inferred without leaking downstream results"
      ],
      "blocking_issue": "No audited artifact yet shows verification_type as a clean standalone field."
    },
    "worker_type": {
      "status": "second_pass_artifact_search_required",
      "source_artifacts": [
        {
          "path_glob": "CLionProjects/whetstone_DSL/logs/taskitem_runs/*",
          "role": "supporting_context"
        }
      ],
      "source_fields": {
        "context_fields": [],
        "label_fields": []
      },
      "allowed_context_fields": [
        "routing-time task metadata only"
      ],
      "forbidden_context_fields": [
        "final execution outputs",
        "post-hoc review outcome"
      ],
      "label_shape": "enum",
      "label_schema": {
        "accepted_values": [
          "implementer",
          "reviewer",
          "architect",
          "qa"
        ]
      },
      "default_provenance": "reconstructed",
      "rejection_rules": [
        "no clean serialized worker label is present in the artifact family"
      ],
      "blocking_issue": "No clean serialized worker_type label found yet in audited taskitem-generation artifacts."
    },
    "cpp_raising_profile": {
      "status": "second_pass_artifact_search_required",
      "source_artifacts": [
        {
          "path_glob": "CLionProjects/whetstone_DSL/logs/taskitem_runs/*",
          "role": "supporting_context"
        }
      ],
      "source_fields": {
        "context_fields": [],
        "label_fields": []
      },
      "allowed_context_fields": [
        "raising-time IR and tool invocation context"
      ],
      "forbidden_context_fields": [
        "post-hoc build outcome used as the label source"
      ],
      "label_shape": "enum",
      "label_schema": {
        "accepted_values": [
          "safe-first",
          "perf-first",
          "interop-first"
        ]
      },
      "default_provenance": "untrusted",
      "rejection_rules": [
        "no clean serialized raising profile label is present in the artifact family"
      ],
      "blocking_issue": "No clean serialized cpp_raising_profile label found yet in audited generic taskitem corpora."
    }
  }
}