id: 1c-tools
name: 1C Tool Contract
status: draft
rules:
  - "Do not invent 1C metadata. Request metadata through tools when object structure matters."
  - "Do not expose credentials, connection strings, tokens, personal data, or client secrets."
  - "Prefer read-only tools by default."
tools:
  - id: get_1c_metadata
    mode: read
    description: "Get available 1C metadata objects by kind."
    input_schema:
      type: object
      required:
        - object_kind
      properties:
        object_kind:
          type: string
          enum:
            - document
            - catalog
            - register
            - all
    output_notes:
      - "Return object names, kinds, and available fields when supported by the backend."
      - "Never include secrets or database credentials."
  - id: search_1c_modules
    mode: read
    description: "Search BSL modules by text or object name."
    status: planned
  - id: explain_bsl_error
    mode: local
    description: "Explain a BSL error message and propose safe fixes."
    status: planned
  - id: check_1c_query
    mode: local
    description: "Check a 1C query for common syntax and semantic issues."
    status: draft
    policy: plugins/1c/connector/policies/read-only-query.yaml
    command: scripts/validate_1c_readonly_query.py
  - id: compare_1c_saved_state_objects
    mode: read
    description: "Compare saved-but-not-applied 1C state with active state and return changes in configurator object terms."
    status: draft
    command: scripts/compare_1c_saved_state_objects.ps1
    output_schema: onec_saved_state_object_comparison.v1
    safety:
      - "Read-only SQL access."
      - "Compares ConfigSave with Config and ConfigCASSave with ConfigCAS."
      - "Returns public object changes as 1C configurator objects, not SQL table names."
      - "Keeps FileName/hash details only as storage evidence."
      - "Does not perform SQL writes."
  - id: analyze_1c_saved_state_object_details
    mode: read
    description: "Analyze saved-state object changes inside changed payloads and return object-level detail hints."
    status: draft
    command: scripts/analyze_1c_saved_state_object_details.py
    output_schema: onec_saved_state_object_detail.v1
    safety:
      - "Read-only file analysis."
      - "Consumes saved-state object comparison plus exported active/saved payload files."
      - "Returns text deltas, added/removed words, and saved form/module string samples in 1C object context."
      - "Does not perform SQL writes."
  - id: build_1c_saved_state_object_report
    mode: read
    description: "Build one read-only saved-state report: object comparison, required SQL payload exports, object detail analysis, and Markdown summary."
    status: draft
    command: scripts/build_1c_saved_state_object_report.ps1
    output_schema: onec_saved_state_object_report.v1
    preferred_for:
      - "Agent needs to inspect saved-but-not-applied Designer changes."
      - "User asks what changed in Configurator after saving but before applying."
    safety:
      - "Read-only SQL access."
      - "Orchestrates compare_1c_saved_state_objects and analyze_1c_saved_state_object_details."
      - "Exports only payload evidence needed for object-level comparison."
      - "Returns public changes as 1C configurator objects, not SQL table names."
      - "Includes agent_summary for compact agent-facing follow-up decisions."
      - "Classifies payload parts with roles and filtered semantic term hints."
      - "Writes a human-readable Markdown report by default."
      - "Runs check_1c_saved_state_object_report as a final contract gate."
      - "Does not perform SQL writes."
  - id: check_1c_saved_state_object_report
    mode: local
    description: "Validate saved-state object report JSON, linked detail/comparison files, safety flags, agent_summary, payload roles, and semantic hints."
    status: draft
    command: scripts/check_1c_saved_state_object_report.py
    output_schema: onec_saved_state_object_report_check.v1
    safety:
      - "Read-only validation."
      - "Rejects missing linked comparison/detail/Markdown files."
      - "Rejects unstable agent_summary array fields and unknown payload roles."
      - "Rejects reports that do not preserve read-only safety flags."
  - id: get_1c_saved_state_object_change
    mode: local
    description: "Return one changed 1C object from a saved-state object report by configurator-visible name."
    status: draft
    command: scripts/get_1c_saved_state_object_change.py
    output_schema: onec_saved_state_object_change.v1
    preferred_for:
      - "Agent has a saved-state report and needs only one changed object."
      - "User asks what changed in a specific object after saving in Designer."
    safety:
      - "Read-only JSON lookup."
      - "Searches by full name, short name, synonym, and suffix/contains matches."
      - "Returns candidates instead of guessing when a match is ambiguous."
      - "Keeps SQL storage details as evidence under comparison/detail fields."
  - id: list_1c_saved_state_object_changes
    mode: local
    description: "List changed 1C objects from a saved-state object report with compact filters."
    status: draft
    command: scripts/list_1c_saved_state_object_changes.py
    output_schema: onec_saved_state_object_change_list.v1
    preferred_for:
      - "Agent needs to route a saved-state report before reading details."
      - "User asks which changed objects are modules, forms, extension changes, or missing active parts."
    safety:
      - "Read-only JSON lookup."
      - "Filters by layer, kind, extension, payload role, text diff, and active-missing state."
      - "Returns compact 1C object summaries with payload roles and semantic terms."
  - id: compare_1c_saved_state_object_reports
    mode: local
    description: "Compare two saved-state object reports and return what changed between agent observations in 1C object terms."
    status: draft
    command: scripts/compare_1c_saved_state_object_reports.py
    output_schema: onec_saved_state_object_report_delta.v1
    preferred_for:
      - "Agent needs to know what changed since the previous saved-state report."
      - "User continues editing Designer and asks what is new since the last check."
    safety:
      - "Read-only JSON comparison."
      - "Compares agent_summary objects by 1C full_name and stable payload-part fingerprints."
      - "Returns added, removed, changed, and unchanged 1C objects."
      - "Keeps system changes separate from object changes."
      - "Writes a Markdown delta report by default when --output is provided unless --skip-markdown is used."
      - "Runs check_1c_saved_state_object_report_delta as a final contract gate when --output is provided unless --skip-check is used."
  - id: watch_1c_saved_state_once
    mode: read
    description: "Build one timestamped saved-state report observation and compare it with the previous observation when available."
    status: draft
    command: scripts/watch_1c_saved_state_once.ps1
    output_schema: onec_saved_state_watch_once.v1
    preferred_for:
      - "User is editing Designer and wants the agent to observe saved-state changes repeatedly."
      - "Agent needs a new report plus delta from the previous observation in one command."
    safety:
      - "Read-only SQL access."
      - "Runs build_1c_saved_state_object_report and compare_1c_saved_state_object_reports."
      - "Stores each observation in a timestamped run directory."
      - "Writes a Markdown watch summary by default unless -SkipMarkdown is used."
      - "Runs check_1c_saved_state_watch_once as a final contract gate."
      - "Does not perform SQL writes."
  - id: render_1c_saved_state_watch_once_markdown
    mode: local
    description: "Render a one-shot saved-state watch manifest as compact Markdown."
    status: draft
    command: scripts/render_1c_saved_state_watch_once_markdown.py
    output_schema: markdown
    safety:
      - "Read-only rendering."
      - "Consumes onec_saved_state_watch_once.v1 JSON."
      - "Shows report, delta, checks, counts, and safety."
  - id: check_1c_saved_state_watch_once
    mode: local
    description: "Validate a one-shot saved-state watch manifest and linked report/delta checks."
    status: draft
    command: scripts/check_1c_saved_state_watch_once.py
    output_schema: onec_saved_state_watch_once_check.v1
    safety:
      - "Read-only validation."
      - "Rejects missing linked report, report check, delta, delta check, or mismatched counts."
  - id: list_1c_saved_state_watch_runs
    mode: local
    description: "List timestamped saved-state watch runs under an output root."
    status: draft
    command: scripts/list_1c_saved_state_watch_runs.py
    output_schema: onec_saved_state_watch_run_list.v1
    preferred_for:
      - "Agent needs the latest saved-state watch observation."
      - "User asks what watch runs exist or which runs had delta changes."
    safety:
      - "Read-only filesystem listing."
      - "Returns compact run summaries, linked artifact paths, check statuses, and delta counts."
      - "Supports filters for runs with delta and runs with actual delta changes."
      - "Writes a Markdown run-list report by default when --output is provided unless --skip-markdown is used."
      - "Runs check_1c_saved_state_watch_run_list as a final contract gate when --output is provided unless --skip-check is used."
  - id: check_1c_saved_state_watch_run_list
    mode: local
    description: "Validate saved-state watch run list JSON, linked Markdown, run directories, check statuses, latest item, and counts."
    status: draft
    command: scripts/check_1c_saved_state_watch_run_list.py
    output_schema: onec_saved_state_watch_run_list_check.v1
    safety:
      - "Read-only validation."
      - "Rejects missing linked Markdown when the list JSON declares one."
      - "Rejects missing run directories, check status mismatches, latest mismatch, and count mismatches."
  - id: get_1c_saved_state_latest_watch_run
    mode: local
    description: "Return the latest saved-state watch run under an output root."
    status: draft
    command: scripts/get_1c_saved_state_latest_watch_run.py
    output_schema: onec_saved_state_latest_watch_run.v1
    preferred_for:
      - "Agent needs the most recent saved-state observation and linked artifacts."
      - "User asks for the latest watch result or latest run with delta changes."
    safety:
      - "Read-only filesystem lookup."
      - "Can require a run with delta or a run with actual delta changes."
      - "Returns found=false instead of guessing when no run matches."
      - "Writes a Markdown latest-run report by default when --output is provided unless --skip-markdown is used."
      - "Runs check_1c_saved_state_latest_watch_run as a final contract gate when --output is provided unless --skip-check is used."
  - id: render_1c_saved_state_latest_watch_run_markdown
    mode: local
    description: "Render latest saved-state watch run lookup JSON as compact Markdown."
    status: draft
    command: scripts/render_1c_saved_state_latest_watch_run_markdown.py
    output_schema: markdown
    safety:
      - "Read-only rendering."
      - "Consumes onec_saved_state_latest_watch_run.v1 JSON."
      - "Shows matching requirements, found status, latest run artifacts, counts, and safety."
  - id: check_1c_saved_state_latest_watch_run
    mode: local
    description: "Validate latest saved-state watch run lookup JSON and linked run/check artifacts."
    status: draft
    command: scripts/check_1c_saved_state_latest_watch_run.py
    output_schema: onec_saved_state_latest_watch_run_check.v1
    safety:
      - "Read-only validation."
      - "Accepts found=false when no run matches the requested requirements."
      - "Rejects missing linked run directories, report files, or check status mismatches."
  - id: render_1c_saved_state_watch_run_list_markdown
    mode: local
    description: "Render saved-state watch run list JSON as compact Markdown."
    status: draft
    command: scripts/render_1c_saved_state_watch_run_list_markdown.py
    output_schema: markdown
    safety:
      - "Read-only rendering."
      - "Consumes onec_saved_state_watch_run_list.v1 JSON."
      - "Shows latest run, filters, check statuses, artifact links, and delta counts."
  - id: check_1c_saved_state_object_report_delta
    mode: local
    description: "Validate saved-state report delta JSON, linked Markdown, safety flags, counts, object arrays, payload roles, and changed-part structure."
    status: draft
    command: scripts/check_1c_saved_state_object_report_delta.py
    output_schema: onec_saved_state_object_report_delta_check.v1
    safety:
      - "Read-only validation."
      - "Rejects missing linked Markdown when the delta JSON declares one."
      - "Rejects unstable object arrays and unknown payload roles."
      - "Rejects count mismatches and changed objects with identical before/after fingerprints."
  - id: render_1c_saved_state_object_report_delta_markdown
    mode: local
    description: "Render saved-state report delta JSON as compact Markdown."
    status: draft
    command: scripts/render_1c_saved_state_object_report_delta_markdown.py
    output_schema: markdown
    safety:
      - "Read-only rendering."
      - "Consumes onec_saved_state_object_report_delta.v1 JSON."
      - "Keeps changed 1C objects and system changes separate."
  - id: render_1c_saved_state_object_report_markdown
    mode: local
    description: "Render saved-state object report JSON as a compact human-readable Markdown report."
    status: draft
    command: scripts/render_1c_saved_state_object_report_markdown.py
    output_schema: markdown
    safety:
      - "Read-only rendering."
      - "Consumes saved-state report, comparison, and detail JSON files."
      - "Keeps SQL storage names as evidence while leading with 1C configurator objects."
      - "Limits diff output by default."
  - id: generate_bsl_snippet
    mode: local
    description: "Generate a small BSL snippet from a user task."
    status: planned
  - id: propose_1c_change
    mode: local
    description: "Create a reviewable change proposal. Never applies changes directly."
    status: draft
    policy: plugins/1c/connector/policies/change-workflow.yaml
  - id: validate_1c_patch_workspace_semantics
    mode: local
    description: "Validate editable patch workspace BSL/Form.xml semantics before review or packaging."
    status: draft
    command: scripts/validate_1c_patch_workspace_semantics.py
    output_schema: onec_patch_workspace_semantic_validation.v1
    guarantees:
      - "Parses Form.xml files and rejects invalid XML."
      - "Parses BSL routine declarations and rejects duplicate routines."
      - "Checks basic BSL block balance for procedures, functions, If/For/While/Try blocks."
      - "Checks form command actions against routines in the matching form module when both files are present."
  - id: edit_1c_bsl_routine
    mode: local
    description: "Append, replace, or upsert one BSL procedure/function under a patch workspace working/ file."
    status: draft
    command: scripts/edit_1c_bsl_routine.py
    output_schema: onec_bsl_routine_edit.v1
    safety:
      - "Only edits BSL modules listed in the workspace manifest."
      - "Only writes under working/."
      - "Runs semantic workspace validation after the edit."
      - "Rolls the file back by default when semantic validation fails."
  - id: edit_1c_form_command
    mode: local
    description: "Append, replace, or upsert one Form.xml command under a patch workspace working/ file."
    status: draft
    command: scripts/edit_1c_form_command.py
    output_schema: onec_form_command_edit.v1
    safety:
      - "Only edits Form.xml files listed in the workspace manifest."
      - "Only writes under working/."
      - "Runs semantic workspace validation after the edit."
      - "Rolls the file back by default when semantic validation fails."
    limits:
      - "Edits only the root Commands collection; it does not add visible buttons/items yet."
  - id: edit_1c_form_button
    mode: local
    description: "Append, replace, or upsert one visible Form.xml button under a named parent form item."
    status: draft
    command: scripts/edit_1c_form_button.py
    output_schema: onec_form_button_edit.v1
    safety:
      - "Only edits Form.xml files listed in the workspace manifest."
      - "Only writes under working/."
      - "Requires the target form command to exist before adding the button."
      - "Runs semantic workspace validation after the edit."
      - "Rolls the file back by default when semantic validation fails."
  - id: add_1c_form_button_workflow
    mode: local
    description: "Atomically add or update a BSL handler, Form.xml command, and visible Form.xml button."
    status: draft
    command: scripts/add_1c_form_button_workflow.py
    output_schema: onec_form_button_workflow.v1
    preferred_for:
      - "User asks to add a visible form button."
      - "Agent needs to create the BSL handler, command, and button together."
    safety:
      - "Only edits files listed in the workspace manifest."
      - "Only writes under working/."
      - "Snapshots all working/ manifest files before editing."
      - "Restores the snapshot by default when any step fails."
      - "Runs semantic workspace validation and returns a diff summary."
  - id: create_1c_patch_bundle
    mode: local
    description: "Create a zip review bundle from a ready_for_review patch workspace without applying changes."
    status: draft
    command: scripts/create_1c_patch_bundle.py
    output_schema: onec_patch_bundle_creation.v1
    safety:
      - "Requires preflight status ready_for_review."
      - "Copies only modified working/ files and review evidence."
      - "Does not write to source extension files, SQL, Config, ConfigSave, or ConfigCAS."
      - "Runs bundle validation after creation."
  - id: check_1c_patch_bundle
    mode: local
    description: "Validate a 1C patch review bundle directory and optional zip archive."
    status: draft
    command: scripts/check_1c_patch_bundle.py
    output_schema: onec_patch_bundle_check.v1
    safety:
      - "Read-only validation."
      - "Checks manifest, preflight, diff, copied modified-file hashes, and zip contents."
  - id: create_1c_extension_staging_from_bundle
    mode: local
    description: "Create a disposable extension XML staging copy from a validated patch bundle."
    status: draft
    command: scripts/create_1c_extension_staging_from_bundle.py
    output_schema: onec_extension_staging_creation.v1
    safety:
      - "Requires a valid patch bundle."
      - "Copies the source extension directory to a staging directory."
      - "Overlays only bundle modified files into staging."
      - "Does not modify source extension files, SQL, Config, ConfigSave, or ConfigCAS."
      - "Marks the staging copy as requiring disposable 1C validation."
      - "Runs staging validation after creation."
  - id: check_1c_extension_staging
    mode: local
    description: "Validate a disposable extension XML staging copy."
    status: draft
    command: scripts/check_1c_extension_staging.py
    output_schema: onec_extension_staging_check.v1
    safety:
      - "Read-only validation."
      - "Checks staging manifest schema and safety flags."
      - "Checks staged file hashes against the bundle working hashes."
      - "Checks source extension files still match the hashes recorded during staging."
      - "Revalidates the source review bundle."
  - id: create_1c_extension_validation_plan
    mode: local
    description: "Create a disposable-base validation plan for a staged 1C extension copy."
    status: draft
    command: scripts/create_1c_extension_validation_plan.py
    output_schema: onec_extension_validation_plan.v1
    safety:
      - "Does not launch 1C or modify any base."
      - "Requires a passing staging check."
      - "Requires a passing runner config check when --runner-config is provided."
      - "Marks production base, SQL writes, and source extension writes as forbidden."
      - "Returns required 1C validation checks and evidence files for a future runner."
  - id: check_1c_extension_runner_config
    mode: local
    description: "Validate safe runner configuration for disposable 1C extension validation."
    status: draft
    command: scripts/check_1c_extension_runner_config.py
    output_schema: onec_extension_runner_config_check.v1
    safety:
      - "Read-only validation."
      - "Rejects production-like base references."
      - "Rejects secrets and credentials in runner config."
      - "Requires explicit disposable_base_confirmed=true."
  - id: create_1c_extension_validation_evidence
    mode: local
    description: "Create manual evidence templates for a 1C extension validation plan."
    status: draft
    command: scripts/create_1c_extension_validation_evidence.py
    output_schema: onec_extension_validation_evidence_manifest.v1
    safety:
      - "Does not launch 1C or modify any base."
      - "Requires validation plan status ready_for_disposable_validation."
      - "Creates pending evidence templates only."
      - "Does not mark validation as passed."
  - id: check_1c_extension_validation_evidence
    mode: local
    description: "Check manual evidence files for a 1C extension validation plan."
    status: draft
    command: scripts/check_1c_extension_validation_evidence.py
    output_schema: onec_extension_validation_evidence_check.v1
    safety:
      - "Read-only validation."
      - "Requires every expected evidence file to exist."
      - "Rejects evidence files that still contain pending templates."
      - "Requires explicit passed/success/ok evidence status."
      - "Rejects secret-like key/value text in evidence files."
  - id: check_1c_extension_validation_release
    mode: local
    description: "Aggregate final validation gates for a staged 1C extension."
    status: draft
    command: scripts/check_1c_extension_validation_release.py
    output_schema: onec_extension_validation_release_check.v1
    safety:
      - "Read-only validation."
      - "Requires validation plan status ready_for_disposable_validation."
      - "Requires staging check and evidence check to pass."
      - "Never allows automatic production apply."
      - "Returns validated_for_human_review only after all gates pass."
  - id: render_1c_extension_validation_release_markdown
    mode: local
    description: "Render 1C extension validation release check JSON as Markdown."
    status: draft
    command: scripts/render_1c_extension_validation_release_markdown.py
    output_schema: markdown
    safety:
      - "Read-only rendering."
      - "Preserves the no automatic production apply safety message."