SCRIPTS.json

{
    "index": [
        "add_changelog_entry.py",
        "audit_docs.py",
        "audit_docs.py",
        "audit_json_docs.py",
        "check_code_context_gate.py",
        "check_ai_compiled_context.py",
        "check_ai_compiled_context.py",
        "check_evals.py",
        "check_evals.py",
        "check_pipeline_featurelist_update.py",
        "check_pipeline_feature_contracts.py",
        "check_pipeline_feature_contracts.py",
        "check_sensitive_reference_leaks.py",
        "check_sensitive_reference_leaks.py",
        "check_python_syntax.py",
        "check_runtime.py",
        "script_runtime_gate.py",
        "python_runtime.py",
        "pipeline_package.py",
        "ai_native_contract_dry_run.py",
        "check_task.py",
        "check_utf8_writes.py",
        "legacy_commit_task_compatibility_wrapper.py",
        "compile_pipeline_context.py",
        "compile_pipeline_context.py",
        "generate_installed_agent_instructions.py",
        "console_summary.py",
        "context_tags.py",
        "context_tags.py",
        "detect_project_stack.py",
        "build_document_cache.py",
        "build_document_cache.py",
        "document_item_edit_engine.py",
        "bulk_insert_document_items.py",
        "insert_document_item.py",
        "migrate_document_item.py",
        "move_document_item.py",
        "list_document_keys.py",
        "check_document_list_item_duplicates.py",
        "insert_document_list_item.py",
        "insert_checked_document_list_item.py",
        "document_list_item_edit_engine.py",
        "review_document_list_candidates.py",
        "json_list_doc.py",
        "json_wrapper_entrypoints.py",
        "smoke_json_tools.py",
        "json_refresh_index.py",
        "json_refresh_index.py",
        "json_migrate_content.py",
        "json_migrate_content.py",
        "json_node_edit.py",
        "json_node_edit.py",
        "json_read.py",
        "json_read.py",
        "json_item_insert.py",
        "json_item_insert.py",
        "json_item_set.py",
        "json_item_set.py",
        "json_item_move.py",
        "json_item_move.py",
        "json_item_delete.py",
        "json_item_delete.py",
        "json_line_insert.py",
        "json_line_insert.py",
        "json_line_set.py",
        "json_line_set.py",
        "json_line_move.py",
        "json_line_move.py",
        "run_document_post_edit_checks.py",
        "read_document_item.py",
        "read_document_items_by_title.py",
        "document_read_cache_engine.py",
        "migrate_document_schema.py",
        "document_schema_migration_engine.py",
        "normalize_document_structure.py",
        "document_structure_normalizer_engine.py",
        "check_toolchain_health.py",
        "finalize_task_check_commit_push.py",
        "end_prompt_snapshot.py",
        "end_prompt_snapshot.py",
        "finalize_changed_files_commit_push.py",
        "finalize_changed_files_commit_push.py",
        "run_final_task_checks.py",
        "run_final_task_checks.py",
        "shared_script_parity.py",
        "generate_embedded_config_payload.py",
        "import_existing_project.py",
        "init_branch_memory.py",
        "init_task_work.py",
        "grouped_task_handoff.py",
        "Initialize-SocratexPipeline.py",
        "Initialize-SocratexPipeline.py",
        "knowledge_check.py",
        "knowledge_check.py",
        "knowledge_code_context.py",
        "knowledge_code_context.py",
        "knowledge_compile.py",
        "knowledge_compile.py",
        "knowledge_delete.py",
        "knowledge_delete.py",
        "knowledge_file_check.py",
        "knowledge_file_check.py",
        "knowledge_file_compile.py",
        "knowledge_file_compile.py",
        "knowledge_file_delete.py",
        "knowledge_file_delete.py",
        "knowledge_file_query.py",
        "knowledge_file_query.py",
        "knowledge_file_rename.py",
        "knowledge_file_rename.py",
        "knowledge_file_select.py",
        "knowledge_file_select.py",
        "knowledge_file_upsert.py",
        "knowledge_file_upsert.py",
        "knowledge_index.py",
        "knowledge_tier_report.py",
        "knowledge_tier_report.py",
        "knowledge_tier_check.py",
        "knowledge_tier_check.py",
        "knowledge_query.py",
        "knowledge_query.py",
        "knowledge_rename.py",
        "knowledge_rename.py",
        "knowledge_select.py",
        "knowledge_select.py",
        "knowledge_upsert.py",
        "knowledge_upsert.py",
        "learn_pipeline_features.py",
        "log_summary.py",
        "migrate_ai_pipeline.py",
        "normalize_documents.bat",
        "normalize_json_files.py",
        "normalize_json_files.py",
        "normalize_markdown_emoji.py",
        "normalize_text_files.py",
        "normalize_text_files.py",
        "open_pipeline_learning_issue.py",
        "pipeline_bootstrap_index.py",
        "pipeline_bootstrap_index.py",
        "chain_runner.py",
        "child_sync_smoke.py",
        "context_bootstrap_load.py",
        "final_runtime_gate.py",
        "helper_refactor_smoke.py",
        "no_legacy_shell_verification.py",
        "pipeline_sweep.py",
        "pipeline_sweep.py",
        "source_finalization_precheck.py",
        "resolve_tool_runtime.py",
        "resolve_workspace_root.py",
        "rebuild_ai_compiled_context.py",
        "rebuild_ai_compiled_context.py",
        "reinitialize_pipeline.py",
        "remove_pipeline.py",
        "repair_mojibake.py",
        "repair_mojibake.py",
        "report_pipeline_learning.py",
        "run_quality_fix.py",
        "run_quality_gate.py",
        "run_quality_gate.py",
        "run_quality_gate_contract.py",
        "run_quality_gate_contract.py",
        "set_directives.py",
        "sync_pipeline_featurelist.py",
        "sync_pipeline_featurelist.py",
        "task_snapshot.py",
        "task_snapshot.py",
        "task_flow_audit.py",
        "task_flow_audit.py",
        "update_code_line_index.py",
        "update_code_line_index.py",
        "update_pipeline_from_link.py",
        "update_pipeline_from_link.py",
        "upgrade_from_reference_project.py",
        "utf8_file_helpers.py",
        "utf8_file_helpers.py",
        "run_interactive_setup.py",
        "write_utf8_file.py",
        "write_utf8_file.py",
        "sync_managed_pipeline_package.py",
        "sync_managed_pipeline_package.py",
        "read_compiled_context.py",
        "read_compiled_context.py",
        "tool_error_log.py",
        "tool_handler.py",
        "project_design_context.py",
        "check_project_design_context_gate.py",
        "gpt_shared_conversation_extract.py",
        "gpt_conversation_archive.py"
    ],
    "content": {
        "add_changelog_entry.py": {
            "path": "tools/repo/add_changelog_entry.py",
            "category": "repo",
            "description": "Append a factual shipped-change entry to CHANGELOG.json or CHANGELOG.md.",
            "input": {
                "required": [
                    "-Summary"
                ],
                "optional": [
                    "-Feature",
                    "-Why",
                    "-Version",
                    "-Timestamp",
                    "-Path"
                ],
                "rule": "Pass one concise summary string or a comma-separated list string; avoid shell-specific array conventions."
            },
            "output": {
                "success": "Appends one changelog entry and prints the target feature or timestamp.",
                "failure": "Throws when the changelog path is missing, the timestamp is invalid, or Summary is empty."
            }
        },
        "audit_docs.py": {
            "path": "tools/documents/audit_docs.py",
            "category": "documents",
            "description": "Python-first document audit entrypoint for JSON document contracts and smoke sweeps.",
            "input": {
                "required": [],
                "optional": [
                    "--repo-root",
                    "--strict",
                    "--initialized"
                ],
                "rule": "Run from the repository root or pass --repo-root. This is the Python smoke entrypoint; broader legacy audit parity remains tracked as migration debt until all legacy-shell-only checks are ported."
            },
            "output": {
                "success": "Runs the Python JSON document audit and prints OK when document contracts pass.",
                "failure": "Exits nonzero when JSON documents, generated document cache, or checked template schema rules fail."
            }
        },
        "audit_json_docs.py": {
            "path": "tools/json/audit_json_docs.py",
            "category": [
                "json"
            ],
            "description": "Validate JSON document files for parseability and repository document conventions.",
            "input": {
                "required": [],
                "optional": [
                    "--repo-root"
                ],
                "rule": "Run from the repository root and prefer wrapper scripts over internal engines for normal document edits."
            },
            "output": {
                "success": "Completes the document operation or check and prints the requested result or OK status.",
                "failure": "Throws or exits nonzero when paths, selectors, duplicate policy, schema rules, normalization, or post-edit checks fail."
            }
        },
        "check_code_context_gate.py": {
            "path": "tools/codebase/check_code_context_gate.py",
            "category": "codebase",
            "description": "Verify that required compiled code-guidance context was loaded for the current HEAD before code-changing work.",
            "input": {
                "required": [],
                "optional": [
                    "-Paths",
                    "-MaxAgeMinutes"
                ],
                "rule": "Run from the repository root when verifying codebase context or generated codebase indexes."
            },
            "output": {
                "success": "Completes the codebase verification or reporting step and exits 0 when the contract is satisfied.",
                "failure": "Throws or exits nonzero when required codebase context or generated codebase artifacts are missing or stale."
            }
        },
        "check_ai_compiled_context.py": {
            "path": "tools/pipeline/check_ai_compiled_context.py",
            "category": "pipeline",
            "description": "Python cheap check for compiled-context anchor files and bootstrap-index freshness.",
            "input": {
                "required": [],
                "optional": [
                    "--repo-root",
                    "--output-dir"
                ],
                "rule": "Use for Python-first smoke sweeps when full compiled-context regeneration is not being requested."
            },
            "output": {
                "success": "Prints OK when required compiled-context anchors exist and the bootstrap index is current.",
                "failure": "Exits nonzero when compiled-context anchors are missing or the bootstrap index is stale."
            }
        },
        "check_evals.py": {
            "path": "tools/quality/check_evals.py",
            "category": "quality",
            "description": "Python-first checker for manual eval framework files, prompt scenarios, personas, expected behaviors, scoring docs, and result JSONs.",
            "input": {
                "required": [],
                "optional": [
                    "--repo-root",
                    "--eval-dir"
                ],
                "rule": "Run from the repository root or pass --repo-root. Use --eval-dir only when checking a nonstandard eval directory."
            },
            "output": {
                "success": "Prints OK when required eval files parse and scenario references are consistent.",
                "failure": "Exits nonzero when eval files are missing, invalid JSON, or internally inconsistent."
            }
        },
        "check_pipeline_featurelist_update.py": {
            "path": "tools/repo/check_pipeline_featurelist_update.py",
            "category": "repo",
            "description": "Repository pipeline feature synchronization helper.",
            "input": {
                "required": [],
                "optional": [],
                "rule": "Use documented script parameters for the selected workflow."
            },
            "output": {
                "success": "Exits 0 and prints status when the operation succeeds.",
                "failure": "Throws or exits nonzero with a concrete error."
            }
        },
        "check_pipeline_feature_contracts.py": {
            "path": "tools/repo/check_pipeline_feature_contracts.py",
            "category": "repo",
            "description": "Python-first validator for pipeline_featurelist.json feature artifact contracts and changed pipeline-owned path coverage.",
            "input": {
                "required": [],
                "optional": [
                    "--repo-root",
                    "--paths"
                ],
                "rule": "Use this Python entrypoint for source and installed-package feature contract checks. Pass changed paths for focused task verification; omit paths for a full feature contract audit."
            },
            "output": {
                "success": "Prints the number of covered feature contracts and confirms changed pipeline paths are assigned.",
                "failure": "Exits nonzero when feature contracts, required artifacts, catalog entries, managed-package coverage, or changed-path coverage fail."
            }
        },
        "check_sensitive_reference_leaks.py": {
            "path": "tools/repo/check_sensitive_reference_leaks.py",
            "category": "repo",
            "description": "Python-first smoke-test for private project, private domain, and private identity references before publication or pipeline sync.",
            "input": {
                "required": [],
                "optional": [
                    "--repo-root",
                    "--max-findings"
                ],
                "rule": "Run without arguments from the source pipeline repository; pass --repo-root only when checking another checkout."
            },
            "output": {
                "success": "Exits 0 when no blocked private references are found.",
                "failure": "Exits nonzero and prints file, line, rule, and matched text for every blocked reference up to max findings."
            }
        },
        "check_python_syntax.py": {
            "path": "tools/quality/check_python_syntax.py",
            "category": "quality",
            "description": "Check Python source syntax in memory without writing bytecode cache files.",
            "input": {
                "required": [
                    "paths"
                ],
                "optional": [
                    "--repo-root"
                ],
                "rule": "Use this instead of py_compile for Python-first quality gates that must not create __pycache__ artifacts."
            },
            "output": {
                "success": "Prints OK with the number of checked Python files.",
                "failure": "Exits nonzero when a source file is missing or cannot compile."
            }
        },
        "check_runtime.py": {
            "path": "tools/quality/check_runtime.py",
            "category": "quality",
            "description": "Report required Python runtime availability as JSON for setup, update, and degraded-mode decisions.",
            "input": {
                "required": [],
                "optional": [
                    "--root-key",
                    "--profile",
                    "--strict",
                    "--json"
                ],
                "rule": "Run through the current Python runtime when setup or update needs toolchain status; set SOCRATEX_PYTHON to override discovery."
            },
            "output": {
                "success": "Prints a JSON object with Python availability, version, executable, source, minimum/recommended version, and install hints.",
                "failure": "With --strict, exits nonzero when Python 3.10+ cannot be resolved."
            }
        },
        "script_runtime_gate.py": {
            "path": "tools/quality/script_runtime_gate.py",
            "category": "quality",
            "description": "Python gate that fails while tracked automation still contains retired script files or canonical references to the retired command runtime.",
            "input": {
                "required": [],
                "optional": [
                    "--repo-root",
                    "--json",
                    "--write-report",
                    "--max-examples",
                    "--max-line-length",
                    "--skip-part"
                ],
                "rule": "Run from the repository root or pass --repo-root. Do not pass --skip-part for final verification; it exists only for local exploratory slicing."
            },
            "output": {
                "success": "Exits 0 and reports pass when no retired script files or canonical retired-runtime references remain.",
                "failure": "Exits nonzero and reports counts, top-level ownership groups, blocked script files, and reference locations."
            }
        },
        "python_runtime.py": {
            "path": "tools/pipeline/python_runtime.py",
            "category": "pipeline",
            "description": "Resolve and report the required SocratexPipeline Python runtime without depending on legacy shell.",
            "input": {
                "required": [],
                "optional": [
                    "--root-key",
                    "--search-root",
                    "--strict"
                ],
                "rule": "Use before Python-first pipeline tools when runtime availability is uncertain. Set SOCRATEX_PYTHON to override discovery."
            },
            "output": {
                "success": "Prints JSON runtime status with executable, version, source, minimum version, and install hint fields.",
                "failure": "With --strict, exits nonzero when Python 3.10+ cannot be resolved."
            }
        },
        "pipeline_package.py": {
            "path": "tools/pipeline/pipeline_package.py",
            "category": "pipeline",
            "description": "Shared managed-package constants for Python-first update and feature-contract tooling.",
            "input": {
                "required": [],
                "optional": [],
                "rule": "Internal helper imported by Python pipeline tools; not normally invoked directly."
            },
            "output": {
                "success": "Provides default managed package, generated, and protected path constants to Python callers.",
                "failure": "Import fails when the source package is missing or Python cannot read the file."
            }
        },
        "ai_native_contract_dry_run.py": {
            "path": "tools/codebase/ai_native_contract_dry_run.py",
            "category": "codebase",
            "description": "Print the AI-native code contract header standard and list likely source files that should receive it in later per-system rollout passes. Dry-run only; it never edits source files.",
            "input": {
                "required": [],
                "optional": [
                    "-ProjectRoot",
                    "-MaxCandidates"
                ],
                "rule": "Run from a project root or pass -ProjectRoot <path>. Use the output as planning/audit evidence, not as an automatic rewrite."
            },
            "output": {
                "success": "Prints the JSON-like comment header standard and a scored candidate file list.",
                "failure": "Throws when ProjectRoot cannot be resolved."
            }
        },
        "check_task.py": {
            "path": "tools/repo/check_task.py",
            "category": "repo",
            "description": "Run the compact repository task check: code-context gate, normalization, bootstrap, diff, UTF-8, feature-list guard, line index, and optional docs audit.",
            "input": {
                "required": [],
                "optional": [
                    "-Paths",
                    "-ProjectRoot",
                    "-Audit",
                    "-MarkdownEmoji",
                    "-NoLineIndex",
                    "-NoNormalize",
                    "-NoStat",
                    "-NoStatus"
                ],
                "rule": "Use before committing changed source-pipeline files; pass -Audit for broad or document-affecting changes."
            },
            "output": {
                "success": "Refreshes/checks selected artifacts and prints OK: task check completed.",
                "failure": "Throws when any selected gate, normalizer check, bootstrap check, audit, or git check fails."
            }
        },
        "check_utf8_writes.py": {
            "path": "tools/text/check_utf8_writes.py",
            "category": "text",
            "description": "Scan repository text writes for unsafe encoding or newline drift.",
            "input": {
                "required": [],
                "optional": [
                    "-Paths"
                ],
                "rule": "Run from the repository root when checking or normalizing repository text files."
            },
            "output": {
                "success": "Completes text normalization, repair, write, or check work and prints OK or the generated output.",
                "failure": "Throws or exits nonzero when files cannot be read/written or check mode finds stale normalization."
            }
        },
        "legacy_commit_task_compatibility_wrapper.py": {
            "path": "tools/repo/legacy_commit_task_compatibility_wrapper.py",
            "category": "repo",
            "description": "Compatibility wrapper that forwards legacy commit-task calls to finalize_changed_files_commit_push.py.",
            "input": {
                "required": [
                    "-Message"
                ],
                "optional": [
                    "-Paths",
                    "-Quality",
                    "-QualityCommand",
                    "-StrictAudit",
                    "-NoAudit",
                    "-NoPush",
                    "-AllowPreStaged"
                ],
                "rule": "Use only for older automation; new flows should call finalize_changed_files_commit_push.py or finalize_task_check_commit_push.py directly."
            },
            "output": {
                "success": "Delegates to the modern finalizer and exits 0 when it succeeds.",
                "failure": "Throws when delegation or the underlying finalizer fails."
            }
        },
        "compile_pipeline_context.py": {
            "path": "tools/pipeline/compile_pipeline_context.py",
            "category": "pipeline",
            "description": "Python orchestration entrypoint for refreshing or checking pipeline bootstrap and AI-compiled context.",
            "input": {
                "required": [],
                "optional": [
                    "--repo-root",
                    "--output-dir",
                    "--check"
                ],
                "rule": "Use this as the Python-first replacement for compile_pipeline_context.py during Pass 0S."
            },
            "output": {
                "success": "Refreshes/checks pipeline bootstrap and AI-compiled context through Python tools.",
                "failure": "Exits nonzero when bootstrap, compiled context generation, or compiled context check fails."
            }
        },
        "generate_installed_agent_instructions.py": {
            "path": "tools/pipeline/generate_installed_agent_instructions.py",
            "category": "pipeline",
            "description": "Generate installed-project AGENTS.md instructions for selected Socratex pipeline packs.",
            "input": {
                "required": [],
                "optional": [
                    "-Packs",
                    "-OutputPath"
                ],
                "rule": "Run from the repository root or an explicit target path when initializing, syncing, compiling, or migrating pipeline packages."
            },
            "output": {
                "success": "Completes the pipeline operation and writes, checks, or prints the requested pipeline artifact.",
                "failure": "Throws or exits nonzero when inputs are invalid, target paths are unsafe, generated artifacts are stale, or pipeline checks fail."
            }
        },
        "console_summary.py": {
            "path": "tools/diagnostics/console_summary.py",
            "category": "diagnostics",
            "description": "Summarize the current console log into a compact diagnostics artifact.",
            "input": {
                "required": [],
                "optional": [
                    "-ConsoleLogPath",
                    "-OutputPath"
                ],
                "rule": "Run from the repository root when producing diagnostics artifacts from logs or console output."
            },
            "output": {
                "success": "Writes or prints the requested diagnostics summary.",
                "failure": "Throws or exits nonzero when log inputs are missing, unreadable, or summary writing fails."
            }
        },
        "context_tags.py": {
            "path": "tools/knowledge/context_tags.py",
            "category": "knowledge",
            "description": "Extract normalized context tags from task text for knowledge selection and routing with Python-only tooling.",
            "input": {
                "required": [],
                "optional": [
                    "text...",
                    "--repo-root",
                    "--no-defaults",
                    "--json",
                    "--as-knowledge-select-args"
                ],
                "rule": "Run from the repository root before substantive answers or command execution when routing through compiled knowledge context."
            },
            "output": {
                "success": "Completes the knowledge operation and prints the selected output, report, or OK status.",
                "failure": "Throws or exits nonzero when source knowledge, compiled artifacts, filters, tiers, or mutation targets are invalid."
            }
        },
        "detect_project_stack.py": {
            "path": "tools/setup/detect_project_stack.py",
            "category": "setup",
            "description": "Detect the target project stack and emit setup hints for pipeline initialization.",
            "input": {
                "required": [],
                "optional": [
                    "-TargetPath"
                ],
                "rule": "Run from the repository root or setup target when checking host/runtime setup."
            },
            "output": {
                "success": "Completes setup probing or configuration and prints the resulting setup status.",
                "failure": "Throws or exits nonzero when runtime detection or requested setup configuration fails."
            }
        },
        "build_document_cache.py": {
            "path": "tools/documents/build_document_cache.py",
            "category": "documents",
            "description": "Build the structured document read cache through Python with a Python entrypoint.",
            "input": {
                "required": [],
                "optional": [
                    "--repo-root",
                    "--output-dir",
                    "paths"
                ],
                "rule": "Use during Pass 0S as the Python replacement for document cache refresh."
            },
            "output": {
                "success": "Writes docs-tech/cache/doc_index.json or the configured output and prints the output path.",
                "failure": "Exits nonzero when document cache generation fails."
            }
        },
        "document_item_edit_engine.py": {
            "path": "tools/documents/document_item_edit_engine.py",
            "category": "documents",
            "description": "Internal engine for inserting, moving, migrating, and reading canonical structured document content items.",
            "input": {
                "required": [],
                "optional": [
                    "--position",
                    "--before",
                    "--after",
                    "--title",
                    "--content",
                    "--content-file",
                    "--item-file",
                    "--allow-empty",
                    "--replace",
                    "--keep-source"
                ],
                "rule": "Run from the repository root and prefer wrapper scripts over internal engines for normal document edits."
            },
            "output": {
                "success": "Completes the document operation or check and prints the requested result or OK status.",
                "failure": "Throws or exits nonzero when paths, selectors, duplicate policy, schema rules, normalization, or post-edit checks fail."
            }
        },
        "bulk_insert_document_items.py": {
            "path": "tools/documents/bulk_insert_document_items.py",
            "category": "documents",
            "description": "Insert multiple structured document items from a payload file through the document edit engine.",
            "input": {
                "required": [
                    "-Path",
                    "-ItemsFile"
                ],
                "optional": [
                    "-Position",
                    "-Before",
                    "-After",
                    "-Replace",
                    "-NoPostEdit"
                ],
                "rule": "Run from the repository root and prefer wrapper scripts over internal engines for normal document edits."
            },
            "output": {
                "success": "Completes the document operation or check and prints the requested result or OK status.",
                "failure": "Throws or exits nonzero when paths, selectors, duplicate policy, schema rules, normalization, or post-edit checks fail."
            }
        },
        "insert_document_item.py": {
            "path": "tools/documents/insert_document_item.py",
            "category": "documents",
            "description": "Insert a canonical JSON document content item; routes .json paths through json_item_insert.py/json_item_set.py and legacy non-JSON structured documents through document_item_edit_engine.py.",
            "input": {
                "required": [
                    "-Path",
                    "-Key"
                ],
                "optional": [
                    "-Title",
                    "-Content",
                    "-ContentFile",
                    "-ItemFile",
                    "-Position",
                    "-Before",
                    "-After",
                    "-AllowEmpty",
                    "-Replace",
                    "-NoPostEdit"
                ],
                "rule": "Use -ContentFile or -ItemFile for multiline or quote-heavy content. For direct JSON control, use json_item_insert.py/json_item_set.py."
            },
            "output": {
                "success": "OK from the underlying document editor.",
                "failure": "Throws child editor failure with the child process exit code."
            }
        },
        "migrate_document_item.py": {
            "path": "tools/documents/migrate_document_item.py",
            "category": "documents",
            "description": "Move or copy one structured document item from a source document to a target document.",
            "input": {
                "required": [
                    "-Source",
                    "-Target",
                    "-Key"
                ],
                "optional": [
                    "-Position",
                    "-Before",
                    "-After",
                    "-KeepSource",
                    "-Replace",
                    "-NoPostEdit"
                ],
                "rule": "Run from the repository root and prefer wrapper scripts over internal engines for normal document edits."
            },
            "output": {
                "success": "Completes the document operation or check and prints the requested result or OK status.",
                "failure": "Throws or exits nonzero when paths, selectors, duplicate policy, schema rules, normalization, or post-edit checks fail."
            }
        },
        "move_document_item.py": {
            "path": "tools/documents/move_document_item.py",
            "category": "documents",
            "description": "Move an item within a structured document while preserving document ordering rules.",
            "input": {
                "required": [
                    "-Path",
                    "-Key"
                ],
                "optional": [
                    "-Position",
                    "-Before",
                    "-After",
                    "-NoPostEdit"
                ],
                "rule": "Run from the repository root and prefer wrapper scripts over internal engines for normal document edits."
            },
            "output": {
                "success": "Completes the document operation or check and prints the requested result or OK status.",
                "failure": "Throws or exits nonzero when paths, selectors, duplicate policy, schema rules, normalization, or post-edit checks fail."
            }
        },
        "list_document_keys.py": {
            "path": "tools/documents/list_document_keys.py",
            "category": "documents",
            "description": "List ordered keys from a structured document for selection and edit planning.",
            "input": {
                "required": [
                    "-Path"
                ],
                "optional": [
                    "-Json"
                ],
                "rule": "Run from the repository root and prefer wrapper scripts over internal engines for normal document edits."
            },
            "output": {
                "success": "Completes the document operation or check and prints the requested result or OK status.",
                "failure": "Throws or exits nonzero when paths, selectors, duplicate policy, schema rules, normalization, or post-edit checks fail."
            }
        },
        "check_document_list_item_duplicates.py": {
            "path": "tools/documents/check_document_list_item_duplicates.py",
            "category": "documents",
            "description": "Check whether a proposed list-document item duplicates existing title, URL, text, or search terms.",
            "input": {
                "required": [
                    "-Path"
                ],
                "optional": [
                    "-Key",
                    "-Scope",
                    "-Text",
                    "-Url",
                    "-Terms",
                    "-Limit",
                    "-Json",
                    "-FailOnDuplicate"
                ],
                "rule": "Run from the repository root and prefer wrapper scripts over internal engines for normal document edits."
            },
            "output": {
                "success": "Completes the document operation or check and prints the requested result or OK status.",
                "failure": "Throws or exits nonzero when paths, selectors, duplicate policy, schema rules, normalization, or post-edit checks fail."
            }
        },
        "insert_document_list_item.py": {
            "path": "tools/documents/insert_document_list_item.py",
            "category": "documents",
            "description": "Insert a validated list-document item while applying duplicate policy and title creation rules.",
            "input": {
                "required": [
                    "-Path",
                    "-Key",
                    "-Text"
                ],
                "optional": [
                    "-Url",
                    "-DuplicateScope",
                    "-CreateTitle",
                    "-AllowDuplicate",
                    "-NoPostEdit"
                ],
                "rule": "Run from the repository root and prefer wrapper scripts over internal engines for normal document edits."
            },
            "output": {
                "success": "Completes the document operation or check and prints the requested result or OK status.",
                "failure": "Throws or exits nonzero when paths, selectors, duplicate policy, schema rules, normalization, or post-edit checks fail."
            }
        },
        "insert_checked_document_list_item.py": {
            "path": "tools/documents/insert_checked_document_list_item.py",
            "category": "documents",
            "description": "Insert a list-document item and run the standard task checks around the edit.",
            "input": {
                "required": [
                    "-Path",
                    "-Key",
                    "-Text"
                ],
                "optional": [
                    "-Url",
                    "-DuplicateScope",
                    "-CreateTitle",
                    "-AllowDuplicate",
                    "-Audit",
                    "-MarkdownEmoji",
                    "-NoLineIndex",
                    "-NoNormalize",
                    "-NoStat",
                    "-NoStatus"
                ],
                "rule": "Run from the repository root and prefer wrapper scripts over internal engines for normal document edits."
            },
            "output": {
                "success": "Completes the document operation or check and prints the requested result or OK status.",
                "failure": "Throws or exits nonzero when paths, selectors, duplicate policy, schema rules, normalization, or post-edit checks fail."
            }
        },
        "document_list_item_edit_engine.py": {
            "path": "tools/documents/document_list_item_edit_engine.py",
            "category": "documents",
            "description": "Internal engine for duplicate checks and list-line insertion in canonical structured document content.",
            "input": {
                "required": [],
                "optional": [
                    "--key",
                    "--scope",
                    "--text",
                    "--url",
                    "--terms",
                    "--limit",
                    "--json",
                    "--fail-on-duplicate",
                    "--titles",
                    "--allow-duplicate",
                    "--create-title"
                ],
                "rule": "Run from the repository root and prefer wrapper scripts over internal engines for normal document edits."
            },
            "output": {
                "success": "Completes the document operation or check and prints the requested result or OK status.",
                "failure": "Throws or exits nonzero when paths, selectors, duplicate policy, schema rules, normalization, or post-edit checks fail."
            }
        },
        "review_document_list_candidates.py": {
            "path": "tools/documents/review_document_list_candidates.py",
            "category": "documents",
            "description": "Preview duplicate candidates for a proposed list-document insertion.",
            "input": {
                "required": [],
                "optional": [
                    "-Path",
                    "-Key",
                    "-Scope",
                    "-Text",
                    "-Url",
                    "-Terms",
                    "-Limit",
                    "-Json",
                    "-FailOnDuplicate"
                ],
                "rule": "Run from the repository root and prefer wrapper scripts over internal engines for normal document edits."
            },
            "output": {
                "success": "Completes the document operation or check and prints the requested result or OK status.",
                "failure": "Throws or exits nonzero when paths, selectors, duplicate policy, schema rules, normalization, or post-edit checks fail."
            }
        },
        "json_list_doc.py": {
            "path": "tools/json/json_list_doc.py",
            "description": "Edit and read list-style JSON source documents while preserving collection order, root indexes, full node paths, and nested list nodes.",
            "input": {
                "required": [],
                "optional": [
                    "--collection",
                    "--position",
                    "--reference",
                    "--text",
                    "--value-json",
                    "--value-json-file",
                    "--value-json-stdin",
                    "--line",
                    "--field-path",
                    "--new-key",
                    "--reference-line",
                    "--reference-text",
                    "--reference-node",
                    "--target-path",
                    "--target-node",
                    "--replace"
                ],
                "rule": "Use wrapper scripts for normal document edits. Use exactly one value source per insert-entry, set-entry, insert-node, or set-node call."
            },
            "output": {
                "success": "Completes the document operation or check and prints the requested result or OK status.",
                "failure": "Non-zero exit with ERROR message on stderr/stdout from the Python wrapper."
            },
            "category": [
                "json"
            ]
        },
        "smoke_json_tools.py": {
            "path": "tools/json/smoke_json_tools.py",
            "description": "Smoke-test portable JSON tooling operations on temporary fixtures: read-node, set-node, insert-node-line, move-node-line, refresh-index, and migrate-content.",
            "input": {
                "required": [],
                "optional": [],
                "rule": "Run from the SocratexAI repository root after moving or changing tools/json helpers."
            },
            "output": {
                "success": "Prints OK when all portable JSON operations behave as expected.",
                "failure": "Non-zero exit with the failed child command or assertion."
            },
            "category": "json"
        },
        "json_refresh_index.py": {
            "path": "tools/json/json_refresh_index.py",
            "category": "json",
            "description": "Python native entrypoint for json_refresh_index JSON document operations.",
            "input": {
                "required": [
                    "path"
                ],
                "optional": [
                    "key",
                    "--collection",
                    "--position",
                    "--reference",
                    "--field-path",
                    "--line",
                    "--text",
                    "--value-json",
                    "--value-json-file",
                    "--value-json-stdin"
                ],
                "rule": "Use this Python wrapper for direct JSON control; use file/stdin value inputs for multiline or quote-heavy JSON."
            },
            "output": {
                "success": "Prints the requested JSON output or OK status after the document operation.",
                "failure": "Exits nonzero when the path, key, node, value input, or JSON document operation is invalid."
            }
        },
        "json_migrate_content.py": {
            "path": "tools/json/json_migrate_content.py",
            "category": "json",
            "description": "Python native entrypoint for json_migrate_content JSON document operations.",
            "input": {
                "required": [
                    "path"
                ],
                "optional": [
                    "key",
                    "--collection",
                    "--position",
                    "--reference",
                    "--field-path",
                    "--line",
                    "--text",
                    "--value-json",
                    "--value-json-file",
                    "--value-json-stdin"
                ],
                "rule": "Use this Python wrapper for direct JSON control; use file/stdin value inputs for multiline or quote-heavy JSON."
            },
            "output": {
                "success": "Prints the requested JSON output or OK status after the document operation.",
                "failure": "Exits nonzero when the path, key, node, value input, or JSON document operation is invalid."
            }
        },
        "json_node_edit.py": {
            "path": "tools/json/json_node_edit.py",
            "category": "json",
            "description": "Python native entrypoint for json_node_edit JSON document operations.",
            "input": {
                "required": [
                    "path"
                ],
                "optional": [
                    "operation",
                    "node",
                    "--path",
                    "--operation",
                    "--node",
                    "--target-path",
                    "--target-node",
                    "--position",
                    "--reference-node",
                    "--line",
                    "--reference-line",
                    "--reference-text",
                    "--text",
                    "--value-json",
                    "--value-json-file",
                    "--value-json-stdin",
                    "--replace"
                ],
                "rule": "Use this Python wrapper for direct JSON control; use file/stdin value inputs for multiline or quote-heavy JSON."
            },
            "output": {
                "success": "Prints the requested JSON output or OK status after the document operation.",
                "failure": "Exits nonzero when the path, key, node, value input, or JSON document operation is invalid."
            }
        },
        "json_read.py": {
            "path": "tools/json/json_read.py",
            "category": "json",
            "description": "Python native entrypoint for json_read JSON document operations.",
            "input": {
                "required": [
                    "path"
                ],
                "optional": [
                    "key",
                    "--collection",
                    "--position",
                    "--reference",
                    "--field-path",
                    "--line",
                    "--text",
                    "--value-json",
                    "--value-json-file",
                    "--value-json-stdin"
                ],
                "rule": "Use this Python wrapper for direct JSON control; use file/stdin value inputs for multiline or quote-heavy JSON."
            },
            "output": {
                "success": "Prints the requested JSON output or OK status after the document operation.",
                "failure": "Exits nonzero when the path, key, node, value input, or JSON document operation is invalid."
            }
        },
        "json_item_insert.py": {
            "path": "tools/json/json_item_insert.py",
            "category": "json",
            "description": "Python native entrypoint for json_item_insert JSON document operations.",
            "input": {
                "required": [
                    "path"
                ],
                "optional": [
                    "key",
                    "--collection",
                    "--position",
                    "--reference",
                    "--field-path",
                    "--line",
                    "--text",
                    "--value-json",
                    "--value-json-file",
                    "--value-json-stdin"
                ],
                "rule": "Use this Python wrapper for direct JSON control; use file/stdin value inputs for multiline or quote-heavy JSON."
            },
            "output": {
                "success": "Prints the requested JSON output or OK status after the document operation.",
                "failure": "Exits nonzero when the path, key, node, value input, or JSON document operation is invalid."
            }
        },
        "json_item_set.py": {
            "path": "tools/json/json_item_set.py",
            "category": "json",
            "description": "Python native entrypoint for json_item_set JSON document operations.",
            "input": {
                "required": [
                    "path"
                ],
                "optional": [
                    "key",
                    "--collection",
                    "--position",
                    "--reference",
                    "--field-path",
                    "--line",
                    "--text",
                    "--value-json",
                    "--value-json-file",
                    "--value-json-stdin"
                ],
                "rule": "Use this Python wrapper for direct JSON control; use file/stdin value inputs for multiline or quote-heavy JSON."
            },
            "output": {
                "success": "Prints the requested JSON output or OK status after the document operation.",
                "failure": "Exits nonzero when the path, key, node, value input, or JSON document operation is invalid."
            }
        },
        "json_item_move.py": {
            "path": "tools/json/json_item_move.py",
            "category": "json",
            "description": "Python native entrypoint for json_item_move JSON document operations.",
            "input": {
                "required": [
                    "path"
                ],
                "optional": [
                    "key",
                    "--collection",
                    "--position",
                    "--reference",
                    "--field-path",
                    "--line",
                    "--text",
                    "--value-json",
                    "--value-json-file",
                    "--value-json-stdin"
                ],
                "rule": "Use this Python wrapper for direct JSON control; use file/stdin value inputs for multiline or quote-heavy JSON."
            },
            "output": {
                "success": "Prints the requested JSON output or OK status after the document operation.",
                "failure": "Exits nonzero when the path, key, node, value input, or JSON document operation is invalid."
            }
        },
        "json_item_delete.py": {
            "path": "tools/json/json_item_delete.py",
            "category": "json",
            "description": "Python native entrypoint for json_item_delete JSON document operations.",
            "input": {
                "required": [
                    "path"
                ],
                "optional": [
                    "key",
                    "--collection",
                    "--position",
                    "--reference",
                    "--field-path",
                    "--line",
                    "--text",
                    "--value-json",
                    "--value-json-file",
                    "--value-json-stdin"
                ],
                "rule": "Use this Python wrapper for direct JSON control; use file/stdin value inputs for multiline or quote-heavy JSON."
            },
            "output": {
                "success": "Prints the requested JSON output or OK status after the document operation.",
                "failure": "Exits nonzero when the path, key, node, value input, or JSON document operation is invalid."
            }
        },
        "json_line_insert.py": {
            "path": "tools/json/json_line_insert.py",
            "category": "json",
            "description": "Python native entrypoint for json_line_insert JSON document operations.",
            "input": {
                "required": [
                    "path"
                ],
                "optional": [
                    "key",
                    "--collection",
                    "--position",
                    "--reference",
                    "--field-path",
                    "--line",
                    "--text",
                    "--value-json",
                    "--value-json-file",
                    "--value-json-stdin"
                ],
                "rule": "Use this Python wrapper for direct JSON control; use file/stdin value inputs for multiline or quote-heavy JSON."
            },
            "output": {
                "success": "Prints the requested JSON output or OK status after the document operation.",
                "failure": "Exits nonzero when the path, key, node, value input, or JSON document operation is invalid."
            }
        },
        "json_line_set.py": {
            "path": "tools/json/json_line_set.py",
            "category": "json",
            "description": "Python native entrypoint for json_line_set JSON document operations.",
            "input": {
                "required": [
                    "path"
                ],
                "optional": [
                    "key",
                    "--collection",
                    "--position",
                    "--reference",
                    "--field-path",
                    "--line",
                    "--text",
                    "--value-json",
                    "--value-json-file",
                    "--value-json-stdin"
                ],
                "rule": "Use this Python wrapper for direct JSON control; use file/stdin value inputs for multiline or quote-heavy JSON."
            },
            "output": {
                "success": "Prints the requested JSON output or OK status after the document operation.",
                "failure": "Exits nonzero when the path, key, node, value input, or JSON document operation is invalid."
            }
        },
        "json_line_move.py": {
            "path": "tools/json/json_line_move.py",
            "category": "json",
            "description": "Python native entrypoint for json_line_move JSON document operations.",
            "input": {
                "required": [
                    "path"
                ],
                "optional": [
                    "key",
                    "--collection",
                    "--position",
                    "--reference",
                    "--field-path",
                    "--line",
                    "--text",
                    "--value-json",
                    "--value-json-file",
                    "--value-json-stdin"
                ],
                "rule": "Use this Python wrapper for direct JSON control; use file/stdin value inputs for multiline or quote-heavy JSON."
            },
            "output": {
                "success": "Prints the requested JSON output or OK status after the document operation.",
                "failure": "Exits nonzero when the path, key, node, value input, or JSON document operation is invalid."
            }
        },
        "run_document_post_edit_checks.py": {
            "path": "tools/documents/run_document_post_edit_checks.py",
            "category": "documents",
            "description": "Run document post-edit cache, audit, normalization, and task-check steps after document edits.",
            "input": {
                "required": [
                    "-Paths"
                ],
                "optional": [
                    "-NoCache",
                    "-Audit",
                    "-NoAudit"
                ],
                "rule": "Run from the repository root and prefer wrapper scripts over internal engines for normal document edits."
            },
            "output": {
                "success": "Completes the document operation or check and prints the requested result or OK status.",
                "failure": "Throws or exits nonzero when paths, selectors, duplicate policy, schema rules, normalization, or post-edit checks fail."
            }
        },
        "read_document_item.py": {
            "path": "tools/documents/read_document_item.py",
            "category": "documents",
            "description": "Read one structured document item by selector, with optional JSON output.",
            "input": {
                "required": [
                    "-Path",
                    "-Selector"
                ],
                "optional": [
                    "-Json"
                ],
                "rule": "Run from the repository root and prefer wrapper scripts over internal engines for normal document edits."
            },
            "output": {
                "success": "Completes the document operation or check and prints the requested result or OK status.",
                "failure": "Throws or exits nonzero when paths, selectors, duplicate policy, schema rules, normalization, or post-edit checks fail."
            }
        },
        "read_document_items_by_title.py": {
            "path": "tools/documents/read_document_items_by_title.py",
            "category": "documents",
            "description": "Read multiple structured document items by title with optional JSON output.",
            "input": {
                "required": [
                    "-Path",
                    "-Titles"
                ],
                "optional": [
                    "-Json"
                ],
                "rule": "Run from the repository root and prefer wrapper scripts over internal engines for normal document edits."
            },
            "output": {
                "success": "Completes the document operation or check and prints the requested result or OK status.",
                "failure": "Throws or exits nonzero when paths, selectors, duplicate policy, schema rules, normalization, or post-edit checks fail."
            }
        },
        "document_read_cache_engine.py": {
            "path": "tools/documents/document_read_cache_engine.py",
            "category": "documents",
            "description": "Internal engine for building and querying cached structured document reads.",
            "input": {
                "required": [],
                "optional": [
                    "--json",
                    "--output-dir",
                    "--repo-root"
                ],
                "rule": "Run from the repository root and prefer wrapper scripts over internal engines for normal document edits."
            },
            "output": {
                "success": "Completes the document operation or check and prints the requested result or OK status.",
                "failure": "Throws or exits nonzero when paths, selectors, duplicate policy, schema rules, normalization, or post-edit checks fail."
            }
        },
        "migrate_document_schema.py": {
            "path": "tools/documents/migrate_document_schema.py",
            "category": "documents",
            "description": "Migrate supported structured documents toward the canonical index/content/metadata schema.",
            "input": {
                "required": [],
                "optional": [
                    "-Paths",
                    "-Check",
                    "-NoPostEdit"
                ],
                "rule": "Run from the repository root and prefer wrapper scripts over internal engines for normal document edits."
            },
            "output": {
                "success": "Completes the document operation or check and prints the requested result or OK status.",
                "failure": "Throws or exits nonzero when paths, selectors, duplicate policy, schema rules, normalization, or post-edit checks fail."
            }
        },
        "document_schema_migration_engine.py": {
            "path": "tools/documents/document_schema_migration_engine.py",
            "category": "documents",
            "description": "Internal engine for structured document schema migration and dry-check mode.",
            "input": {
                "required": [],
                "optional": [
                    "--repo-root",
                    "--check"
                ],
                "rule": "Run from the repository root and prefer wrapper scripts over internal engines for normal document edits."
            },
            "output": {
                "success": "Completes the document operation or check and prints the requested result or OK status.",
                "failure": "Throws or exits nonzero when paths, selectors, duplicate policy, schema rules, normalization, or post-edit checks fail."
            }
        },
        "normalize_document_structure.py": {
            "path": "tools/documents/normalize_document_structure.py",
            "category": "documents",
            "description": "Normalize supported structured documents into canonical index/content/metadata layout and ordering.",
            "input": {
                "required": [],
                "optional": [
                    "-Paths",
                    "-Check",
                    "-NoPostEdit"
                ],
                "rule": "Run from the repository root and prefer wrapper scripts over internal engines for normal document edits."
            },
            "output": {
                "success": "Completes the document operation or check and prints the requested result or OK status.",
                "failure": "Throws or exits nonzero when paths, selectors, duplicate policy, schema rules, normalization, or post-edit checks fail."
            }
        },
        "document_structure_normalizer_engine.py": {
            "path": "tools/documents/document_structure_normalizer_engine.py",
            "category": "documents",
            "description": "Internal engine for structured document normalization and check mode.",
            "input": {
                "required": [],
                "optional": [
                    "--repo-root",
                    "--check"
                ],
                "rule": "Run from the repository root and prefer wrapper scripts over internal engines for normal document edits."
            },
            "output": {
                "success": "Completes the document operation or check and prints the requested result or OK status.",
                "failure": "Throws or exits nonzero when paths, selectors, duplicate policy, schema rules, normalization, or post-edit checks fail."
            }
        },
        "check_toolchain_health.py": {
            "path": "tools/repo/check_toolchain_health.py",
            "category": "repo",
            "description": "Check repository toolchain health and optionally include document audit coverage.",
            "input": {
                "required": [],
                "optional": [
                    "-AuditDocs"
                ],
                "rule": "Run from the repository root as part of task, git, learning, or repository health workflows."
            },
            "output": {
                "success": "Completes the repository workflow step and exits 0 when the requested operation succeeds.",
                "failure": "Throws or exits nonzero when required inputs, repository state, external tooling, or workflow checks fail."
            }
        },
        "finalize_task_check_commit_push.py": {
            "path": "tools/repo/finalize_task_check_commit_push.py",
            "category": "repo",
            "description": "Preferred Git-backed task finalizer: run checks including quality, commit, and push.",
            "input": {
                "required": [
                    "-Message"
                ],
                "optional": [
                    "-QualityCommand",
                    "-StrictAudit",
                    "-NoPush",
                    "-NoAudit",
                    "-AllowPreStaged",
                    "-RequireTaskFlowEvidence",
                    "-TaskFlowEvidencePath"
                ],
                "rule": "Use for normal task closure when changed files should be committed and pushed. It delegates to finalize_changed_files_commit_push.py with quality enabled. Pass -RequireTaskFlowEvidence with -TaskFlowEvidencePath to hard-gate closure on artifact evidence JSON."
            },
            "output": {
                "success": "Checks pass, intentional paths are committed, push runs unless disabled, and final repository state is reported.",
                "failure": "Throws when checks, staging, commit, push, or clean-tree verification fail."
            }
        },
        "end_prompt_snapshot.py": {
            "path": "tools/repo/end_prompt_snapshot.py",
            "category": "repo",
            "description": "Python-first end-of-task OUTPUT snapshot generator.",
            "input": {
                "required": [],
                "optional": [
                    "--root",
                    "--output-path",
                    "--state-tail-lines",
                    "--max-list-items",
                    "--no-sound"
                ],
                "rule": "Use during Pass 0S as the Python replacement for finalizer OUTPUT snapshot generation."
            },
            "output": {
                "success": "Writes the closure snapshot and reports the output path.",
                "failure": "Exits nonzero when repository inspection or output writing fails."
            }
        },
        "finalize_changed_files_commit_push.py": {
            "path": "tools/repo/finalize_changed_files_commit_push.py",
            "category": "repo",
            "description": "Python-first Git-derived changed-file finisher for source-pipeline task closure.",
            "input": {
                "required": [
                    "--message"
                ],
                "optional": [
                    "--repo-root",
                    "--paths",
                    "--no-push",
                    "--no-quality",
                    "--quality-command",
                    "--quality-command-names",
                    "--strict-audit",
                    "--no-audit",
                    "--allow-pre-staged"
                ],
                "rule": "Use during Pass 0S to close source-pipeline tasks through Python final checks, git staging, commit, and optional push."
            },
            "output": {
                "success": "Runs Python-backed final checks, stages git-derived non-local-artifact paths, commits, pushes unless disabled, and reports remaining status.",
                "failure": "Exits nonzero on pre-staged changes unless allowed, empty candidate set, failed checks, failed git operations, or dirty final state."
            }
        },
        "run_final_task_checks.py": {
            "path": "tools/repo/run_final_task_checks.py",
            "category": "repo",
            "description": "Python-first no-commit final verification path for checks that already have Python equivalents.",
            "input": {
                "required": [],
                "optional": [
                    "--repo-root",
                    "--quality",
                    "--quality-command",
                    "--quality-command-names",
                    "--strict-audit",
                    "--no-audit",
                    "--no-compiled-context-check",
                    "--no-cache-check"
                ],
                "rule": "Use during Pass 0S as the Python closure path for check-only verification. It intentionally does not refresh generated artifacts until Python generators exist for every required refresh."
            },
            "output": {
                "success": "Runs Python-backed closure checks and exits 0 after OK.",
                "failure": "Exits nonzero when git diff check, feature contracts, compiled-context anchors, docs audit, quality gate, or Python cache check fails."
            }
        },
        "shared_script_parity.py": {
            "path": "tools/repo/shared_script_parity.py",
            "category": "repo",
            "description": "Audit root/project script parity against an embedded SocratexAI tool package.",
            "input": {
                "required": [],
                "optional": [
                    "--project-root",
                    "--left-root",
                    "--right-root",
                    "--classification-file",
                    "--skip-part",
                    "--suffix",
                    "--json",
                    "--write-report",
                    "--max-examples"
                ],
                "rule": "Defaults compare PROJECT/Tools against PROJECT/SocratexAI/tools, skip bundled runtimes/tmp folders, read PROJECT/Tools/SHARED-SCRIPT-PARITY.json when present, classify exact copies, thin adapters, documented project-specific drift, left-only/right-only files, and fail only on undocumented same-name or same-relative drift."
            },
            "output": {
                "success": "Prints a socratex-shared-script-parity/v1 summary with no drift pairs.",
                "failure": "Returns nonzero when same-name or same-relative project/pipeline script pairs have divergent implementation and are not thin adapters."
            }
        },
        "generate_embedded_config_payload.py": {
            "path": "tools/pipeline/generate_embedded_config_payload.py",
            "category": "pipeline",
            "description": "Generate an embedded configuration payload for pipeline distribution or installation scripts.",
            "input": {
                "required": [],
                "optional": [],
                "rule": "Run from the repository root or an explicit target path when initializing, syncing, compiling, or migrating pipeline packages."
            },
            "output": {
                "success": "Completes the pipeline operation and writes, checks, or prints the requested pipeline artifact.",
                "failure": "Throws or exits nonzero when inputs are invalid, target paths are unsafe, generated artifacts are stale, or pipeline checks fail."
            }
        },
        "import_existing_project.py": {
            "path": "tools/pipeline/import_existing_project.py",
            "category": "pipeline",
            "description": "Import an existing project into a SocratexPipeline layout using selected packs and profile settings.",
            "input": {
                "required": [
                    "-TargetPath"
                ],
                "optional": [
                    "-Packs",
                    "-Profile",
                    "-AiMode",
                    "-Language",
                    "-BranchMode",
                    "-CreateProjectFiles",
                    "-DryRun"
                ],
                "rule": "Run from the repository root or an explicit target path when initializing, syncing, compiling, or migrating pipeline packages."
            },
            "output": {
                "success": "Completes the pipeline operation and writes, checks, or prints the requested pipeline artifact.",
                "failure": "Throws or exits nonzero when inputs are invalid, target paths are unsafe, generated artifacts are stale, or pipeline checks fail."
            }
        },
        "init_branch_memory.py": {
            "path": "tools/pipeline/init_branch_memory.py",
            "category": "pipeline",
            "description": "Initialize branch-scoped memory files and related ignore rules for a project branch.",
            "input": {
                "required": [],
                "optional": [
                    "-Branch",
                    "-BranchFilesDir",
                    "-TemplateDir",
                    "-EnsureGitignore",
                    "-DryRun"
                ],
                "rule": "Run from the repository root or an explicit target path when initializing, syncing, compiling, or migrating pipeline packages."
            },
            "output": {
                "success": "Completes the pipeline operation and writes, checks, or prints the requested pipeline artifact.",
                "failure": "Throws or exits nonzero when inputs are invalid, target paths are unsafe, generated artifacts are stale, or pipeline checks fail."
            }
        },
        "init_task_work.py": {
            "path": "tools/pipeline/init_task_work.py",
            "category": "pipeline",
            "description": "Initialize task work state from a title/source request in the project pipeline workspace.",
            "input": {
                "required": [],
                "optional": [
                    "-Path",
                    "-Title",
                    "-SourceRequest",
                    "-Force",
                    "-DryRun"
                ],
                "rule": "Run from the repository root or an explicit target path when initializing, syncing, compiling, or migrating pipeline packages."
            },
            "output": {
                "success": "Completes the pipeline operation and writes, checks, or prints the requested pipeline artifact.",
                "failure": "Throws or exits nonzero when inputs are invalid, target paths are unsafe, generated artifacts are stale, or pipeline checks fail."
            }
        },
        "grouped_task_handoff.py": {
            "path": "tools/tasks/grouped_task_handoff.py",
            "category": "tasks",
            "description": "Write grouped fragmented-task STATE/PLAN handoff JSON and an optional next-subtask prompt.",
            "input": {
                "required": [
                    "-TaskId",
                    "-GroupId",
                    "-SubtaskId"
                ],
                "optional": [
                    "-ProjectRoot",
                    "-Status",
                    "-GroupGoal",
                    "-SubtaskGoal",
                    "-HandoffSummary",
                    "-InspectedFiles",
                    "-ChangedFiles",
                    "-Verification",
                    "-Risks",
                    "-NextFiles",
                    "-NextCommands",
                    "-NextSubtaskId",
                    "-NextSubtaskGoal",
                    "-HandoffPath",
                    "-PromptPath",
                    "-NoPrompt",
                    "-PrintJson"
                ],
                "rule": "Use named parameters only. From shell, pass list values as one quoted comma-separated string; positional binding is disabled to prevent accidental path shifts."
            },
            "output": {
                "success": "Updates handoff JSON, writes next-subtask prompt unless -NoPrompt is passed, and prints both paths.",
                "failure": "Throws on invalid existing handoff JSON or missing required ids."
            }
        },
        "Initialize-SocratexPipeline.py": {
            "path": "tools/pipeline/Initialize-SocratexPipeline.py",
            "category": "pipeline",
            "description": "Python-first dry-run smoke for SocratexPipeline project initialization.",
            "input": {
                "required": [
                    "--dry-run"
                ],
                "optional": [
                    "--project-name",
                    "--language",
                    "--ai-mode",
                    "--first-target",
                    "--first-session-success",
                    "--communication-profile",
                    "--use-changelog",
                    "--use-git",
                    "--ai-may-commit",
                    "--ai-may-push",
                    "--branch-mode",
                    "--external-changes-possible",
                    "--force-ddd-adiv",
                    "--import-pipeline-package",
                    "--package-manager-detection",
                    "--project-lifecycle",
                    "--test-coverage",
                    "--framework",
                    "--framework-kind",
                    "--linter",
                    "--ci",
                    "--docs",
                    "--team-size",
                    "--velocity",
                    "--highest-pain",
                    "--stack-tags",
                    "--branch-files-language",
                    "--directive-mode",
                    "--keep-packs",
                    "--create-files",
                    "--compile-agent",
                    "--run-audit"
                ],
                "rule": "Use during Pass 0S quality gates as the Python-only replacement for initializer dry-run validation; write-mode remains legacy until the full initializer port."
            },
            "output": {
                "success": "Prints the initialization dry-run plan, validates communication profile and pack names, and exits 0 without writing files.",
                "failure": "Exits nonzero when options are invalid, pack/profile names are unknown, or --dry-run is omitted."
            }
        },
        "knowledge_check.py": {
            "path": "tools/knowledge/knowledge_check.py",
            "category": "knowledge",
            "description": "Verify compiled SQLite knowledge artifacts against source knowledge documents with Python-only tooling, with JSON file fallback validation.",
            "input": {
                "required": [],
                "optional": [
                    "--repo-root"
                ],
                "rule": "Run from the repository root after source knowledge changes or when selecting compiled knowledge context using the Python wrapper."
            },
            "output": {
                "success": "Completes the knowledge operation and prints the selected output, report, or OK status.",
                "failure": "Throws or exits nonzero when source knowledge, compiled artifacts, filters, tiers, or mutation targets are invalid."
            }
        },
        "knowledge_code_context.py": {
            "path": "tools/knowledge/knowledge_code_context.py",
            "category": "knowledge",
            "description": "Load the full compiled engineering/code guidance set and write the freshness marker used by code-context gates with Python-only tooling.",
            "input": {
                "required": [],
                "optional": [
                    "--views",
                    "--additional-tags",
                    "--format",
                    "--skip-check"
                ],
                "rule": "Run before code-touching work during the Python-only migration, or when check_code_context_gate.py reports a stale/missing marker."
            },
            "output": {
                "success": "Prints the loaded code-guidance rules and writes ignored/code_context_gate.json for the current HEAD.",
                "failure": "Exits nonzero when compiled knowledge is stale, unavailable, or missing required guidance coverage."
            }
        },
        "knowledge_compile.py": {
            "path": "tools/knowledge/knowledge_compile.py",
            "category": "knowledge",
            "description": "Compile source knowledge documents into the SQLite knowledge database and JSON fallback with Python-only tooling.",
            "input": {
                "required": [],
                "optional": [
                    "--repo-root"
                ],
                "rule": "Run from the repository root after source knowledge changes or when selecting compiled knowledge context using the Python wrapper."
            },
            "output": {
                "success": "Completes the knowledge operation and prints the selected output, report, or OK status.",
                "failure": "Throws or exits nonzero when source knowledge, compiled artifacts, filters, tiers, or mutation targets are invalid."
            }
        },
        "knowledge_delete.py": {
            "path": "tools/knowledge/knowledge_delete.py",
            "category": "knowledge",
            "description": "Delete a knowledge entry or document from the SQLite knowledge database with Python-only tooling.",
            "input": {
                "required": [
                    "-Path"
                ],
                "optional": [
                    "--repo-root",
                    "--path",
                    "--name"
                ],
                "rule": "Run from the repository root using the Python wrapper."
            },
            "output": {
                "success": "Completes the knowledge operation and prints the selected output, report, or OK status.",
                "failure": "Throws or exits nonzero when source knowledge, compiled artifacts, filters, tiers, or mutation targets are invalid."
            }
        },
        "knowledge_file_check.py": {
            "path": "tools/knowledge/knowledge_file_check.py",
            "category": "knowledge",
            "description": "Verify JSON file-fallback knowledge artifacts against source knowledge documents with Python-only tooling.",
            "input": {
                "required": [],
                "optional": [
                    "--repo-root"
                ],
                "rule": "Run from the repository root after source knowledge changes or when selecting compiled knowledge context using the Python wrapper."
            },
            "output": {
                "success": "Completes the knowledge operation and prints the selected output, report, or OK status.",
                "failure": "Throws or exits nonzero when source knowledge, compiled artifacts, filters, tiers, or mutation targets are invalid."
            }
        },
        "knowledge_file_compile.py": {
            "path": "tools/knowledge/knowledge_file_compile.py",
            "category": "knowledge",
            "description": "Compile source knowledge documents into JSON file-fallback knowledge tables with Python-only tooling.",
            "input": {
                "required": [],
                "optional": [
                    "--repo-root"
                ],
                "rule": "Run from the repository root after source knowledge changes or when selecting compiled knowledge context using the Python wrapper."
            },
            "output": {
                "success": "Completes the knowledge operation and prints the selected output, report, or OK status.",
                "failure": "Throws or exits nonzero when source knowledge, compiled artifacts, filters, tiers, or mutation targets are invalid."
            }
        },
        "knowledge_file_delete.py": {
            "path": "tools/knowledge/knowledge_file_delete.py",
            "category": "knowledge",
            "description": "Delete a knowledge entry or document from JSON file-fallback knowledge tables with Python-only tooling.",
            "input": {
                "required": [
                    "-Path"
                ],
                "optional": [
                    "--repo-root",
                    "--path",
                    "--name"
                ],
                "rule": "Run from the repository root using the Python wrapper."
            },
            "output": {
                "success": "Completes the knowledge operation and prints the selected output, report, or OK status.",
                "failure": "Throws or exits nonzero when source knowledge, compiled artifacts, filters, tiers, or mutation targets are invalid."
            }
        },
        "knowledge_file_query.py": {
            "path": "tools/knowledge/knowledge_file_query.py",
            "category": "knowledge",
            "description": "Query JSON file-fallback knowledge tables with Python-only tooling.",
            "input": {
                "required": [],
                "optional": [
                    "--repo-root",
                    "--tags",
                    "--match",
                    "--type",
                    "--load-at-start",
                    "--context-tier",
                    "--max-context-tier",
                    "--source-path",
                    "--document-path",
                    "--name",
                    "--format"
                ],
                "rule": "Run from the repository root using the Python wrapper."
            },
            "output": {
                "success": "Completes the knowledge operation and prints the selected output, report, or OK status.",
                "failure": "Throws or exits nonzero when source knowledge, compiled artifacts, filters, tiers, or mutation targets are invalid."
            }
        },
        "knowledge_file_rename.py": {
            "path": "tools/knowledge/knowledge_file_rename.py",
            "category": "knowledge",
            "description": "Rename a knowledge source path in JSON file-fallback knowledge tables with Python-only tooling.",
            "input": {
                "required": [
                    "-OldPath",
                    "-NewPath"
                ],
                "optional": [
                    "--repo-root",
                    "--old-path",
                    "--new-path"
                ],
                "rule": "Run from the repository root using the Python wrapper."
            },
            "output": {
                "success": "Completes the knowledge operation and prints the selected output, report, or OK status.",
                "failure": "Throws or exits nonzero when source knowledge, compiled artifacts, filters, tiers, or mutation targets are invalid."
            }
        },
        "knowledge_file_select.py": {
            "path": "tools/knowledge/knowledge_file_select.py",
            "category": "knowledge",
            "description": "Select formatted knowledge context from JSON file-fallback tables with Python-only tooling.",
            "input": {
                "required": [],
                "optional": [
                    "--repo-root",
                    "--tags",
                    "--match",
                    "--type",
                    "--load-at-start",
                    "--context-tier",
                    "--max-context-tier",
                    "--source-path",
                    "--document-path",
                    "--name",
                    "--format"
                ],
                "rule": "Run from the repository root after source knowledge changes or when selecting compiled knowledge context using the Python wrapper."
            },
            "output": {
                "success": "Completes the knowledge operation and prints the selected output, report, or OK status.",
                "failure": "Throws or exits nonzero when source knowledge, compiled artifacts, filters, tiers, or mutation targets are invalid."
            }
        },
        "knowledge_file_upsert.py": {
            "path": "tools/knowledge/knowledge_file_upsert.py",
            "category": "knowledge",
            "description": "Upsert source documents into JSON file-fallback knowledge tables with Python-only tooling.",
            "input": {
                "required": [
                    "-Path"
                ],
                "optional": [
                    "--repo-root",
                    "--path"
                ],
                "rule": "Run from the repository root using the Python wrapper."
            },
            "output": {
                "success": "Completes the knowledge operation and prints the selected output, report, or OK status.",
                "failure": "Throws or exits nonzero when source knowledge, compiled artifacts, filters, tiers, or mutation targets are invalid."
            }
        },
        "knowledge_index.py": {
            "path": "tools/knowledge/knowledge_index.py",
            "category": "knowledge",
            "description": "Internal engine for compiling, querying, selecting, renaming, and mutating knowledge indexes.",
            "input": {
                "required": [],
                "optional": [
                    "--repo-root",
                    "--db",
                    "--manifest",
                    "--file-dir",
                    "--path",
                    "--old-path",
                    "--new-path",
                    "--name",
                    "--tags",
                    "--match",
                    "--type",
                    "--view",
                    "--load-at-start",
                    "--context-tier",
                    "--max-context-tier",
                    "--source-path",
                    "--document-path",
                    "--format"
                ],
                "rule": "Run from the repository root after source knowledge changes or when selecting compiled knowledge context."
            },
            "output": {
                "success": "Completes the knowledge operation and prints the selected output, report, or OK status.",
                "failure": "Throws or exits nonzero when source knowledge, compiled artifacts, filters, tiers, or mutation targets are invalid."
            }
        },
        "knowledge_tier_report.py": {
            "path": "tools/knowledge/knowledge_tier_report.py",
            "category": "knowledge",
            "description": "Report source knowledge documentation entries grouped by context_tier, categories/tags, type, and document path.",
            "input": {
                "required": [],
                "optional": [
                    "-RepoRoot",
                    "-IncludeTemplates",
                    "-Strict",
                    "-ShowEntries",
                    "-Format markdown|json",
                    "-Backend auto|documents|knowledge_files|sqlite",
                    "--db",
                    "--file-dir"
                ],
                "rule": "Use for tier audits and category summaries; add -Strict to turn missing or invalid tiers into a failing check. Use -Backend documents for source-document truth, knowledge_files or sqlite for compiled caches, and auto to prefer current SQLite then file fallback then documents."
            },
            "output": {
                "success": "Prints markdown or JSON summary with backend, counts by tier, category, and explicit tier coverage status.",
                "failure": "With -Strict, exits nonzero when missing/invalid context_tier entries or JSON parse errors are found."
            }
        },
        "knowledge_tier_check.py": {
            "path": "tools/knowledge/knowledge_tier_check.py",
            "category": "knowledge",
            "description": "Python-first strict checker for context_tier metadata on knowledge documentation entries.",
            "input": {
                "required": [],
                "optional": [
                    "--repo-root",
                    "--include-templates",
                    "--format",
                    "--backend auto|documents|knowledge_files|sqlite",
                    "--db",
                    "--file-dir"
                ],
                "rule": "Run after knowledge tier migrations or before relying on tier-scoped context routing. Use --backend documents when compiled knowledge should not be required; use --backend auto when current compiled caches are acceptable."
            },
            "output": {
                "success": "Prints a tier coverage report with selected backend and exits 0 when every discovered knowledge entry has a valid context_tier.",
                "failure": "Exits nonzero and lists missing or invalid context_tier entries or parse errors."
            }
        },
        "knowledge_query.py": {
            "path": "tools/knowledge/knowledge_query.py",
            "category": "knowledge",
            "description": "Query the SQLite knowledge database with Python-only tooling.",
            "input": {
                "required": [],
                "optional": [
                    "--repo-root",
                    "--tags",
                    "--match",
                    "--type",
                    "--load-at-start",
                    "--context-tier",
                    "--max-context-tier",
                    "--source-path",
                    "--document-path",
                    "--name",
                    "--format"
                ],
                "rule": "Run from the repository root using the Python wrapper."
            },
            "output": {
                "success": "Completes the knowledge operation and prints the selected output, report, or OK status.",
                "failure": "Throws or exits nonzero when source knowledge, compiled artifacts, filters, tiers, or mutation targets are invalid."
            }
        },
        "knowledge_rename.py": {
            "path": "tools/knowledge/knowledge_rename.py",
            "category": "knowledge",
            "description": "Rename a knowledge source path in the SQLite database with Python-only tooling.",
            "input": {
                "required": [
                    "-OldPath",
                    "-NewPath"
                ],
                "optional": [
                    "--repo-root",
                    "--old-path",
                    "--new-path"
                ],
                "rule": "Run from the repository root using the Python wrapper."
            },
            "output": {
                "success": "Completes the knowledge operation and prints the selected output, report, or OK status.",
                "failure": "Throws or exits nonzero when source knowledge, compiled artifacts, filters, tiers, or mutation targets are invalid."
            }
        },
        "knowledge_select.py": {
            "path": "tools/knowledge/knowledge_select.py",
            "category": "knowledge",
            "description": "Select formatted knowledge context from compiled SQLite knowledge or file fallback with Python-only tooling.",
            "input": {
                "required": [],
                "optional": [
                    "--tags",
                    "--match",
                    "--type",
                    "--view",
                    "--load-at-start",
                    "--context-tier",
                    "--max-context-tier",
                    "--source-path",
                    "--document-path",
                    "--name",
                    "--file-fallback",
                    "--format"
                ],
                "rule": "Run from the repository root when a named view, tag query, type filter, source document, or startup flag can answer the task."
            },
            "output": {
                "success": "Completes the knowledge operation and prints the selected output, report, or OK status.",
                "failure": "Throws or exits nonzero when source knowledge, compiled artifacts, filters, tiers, or mutation targets are invalid."
            }
        },
        "knowledge_upsert.py": {
            "path": "tools/knowledge/knowledge_upsert.py",
            "category": "knowledge",
            "description": "Upsert source documents into the SQLite knowledge database with Python-only tooling.",
            "input": {
                "required": [
                    "-Path"
                ],
                "optional": [
                    "--repo-root",
                    "--path"
                ],
                "rule": "Run from the repository root using the Python wrapper."
            },
            "output": {
                "success": "Completes the knowledge operation and prints the selected output, report, or OK status.",
                "failure": "Throws or exits nonzero when source knowledge, compiled artifacts, filters, tiers, or mutation targets are invalid."
            }
        },
        "learn_pipeline_features.py": {
            "path": "tools/repo/learn_pipeline_features.py",
            "category": "repo",
            "description": "Repository pipeline feature synchronization helper.",
            "input": {
                "required": [],
                "optional": [],
                "rule": "Use documented script parameters for the selected workflow."
            },
            "output": {
                "success": "Exits 0 and prints status when the operation succeeds.",
                "failure": "Throws or exits nonzero with a concrete error."
            }
        },
        "log_summary.py": {
            "path": "tools/diagnostics/log_summary.py",
            "category": "diagnostics",
            "description": "Summarize one or more task logs into a compact diagnostics output file.",
            "input": {
                "required": [
                    "-Description"
                ],
                "optional": [
                    "-LogsPath",
                    "-TailLines",
                    "-OutputPath"
                ],
                "rule": "Run from the repository root when producing diagnostics artifacts from logs or console output."
            },
            "output": {
                "success": "Writes or prints the requested diagnostics summary.",
                "failure": "Throws or exits nonzero when log inputs are missing, unreadable, or summary writing fails."
            }
        },
        "migrate_ai_pipeline.py": {
            "path": "tools/pipeline/migrate_ai_pipeline.py",
            "category": "pipeline",
            "description": "Migrate an older AI pipeline installation to the current SocratexPipeline template and pack layout.",
            "input": {
                "required": [],
                "optional": [
                    "-TargetPath",
                    "-LegacyDirectiveFiles",
                    "-Packs",
                    "-DirectiveMode",
                    "-CreateProjectFiles",
                    "-DryRun"
                ],
                "rule": "Run from the repository root or an explicit target path when initializing, syncing, compiling, or migrating pipeline packages."
            },
            "output": {
                "success": "Completes the pipeline operation and writes, checks, or prints the requested pipeline artifact.",
                "failure": "Throws or exits nonzero when inputs are invalid, target paths are unsafe, generated artifacts are stale, or pipeline checks fail."
            }
        },
        "normalize_documents.bat": {
            "path": "tools/text/normalize_documents.bat",
            "category": "text",
            "description": "Windows convenience wrapper for repository document normalization.",
            "input": {
                "required": [],
                "optional": [],
                "rule": "Run from the repository root when checking or normalizing repository text files."
            },
            "output": {
                "success": "Completes text normalization, repair, write, or check work and prints OK or the generated output.",
                "failure": "Throws or exits nonzero when files cannot be read/written or check mode finds stale normalization."
            }
        },
        "normalize_json_files.py": {
            "path": "tools/text/normalize_json_files.py",
            "category": "text",
            "description": "Internal JSON normalizer preserving repository formatting conventions.",
            "input": {
                "required": [],
                "optional": [
                    "--repo-root",
                    "--check"
                ],
                "rule": "Run from the repository root when checking or normalizing repository text files."
            },
            "output": {
                "success": "Completes text normalization, repair, write, or check work and prints OK or the generated output.",
                "failure": "Throws or exits nonzero when files cannot be read/written or check mode finds stale normalization."
            }
        },
        "normalize_markdown_emoji.py": {
            "path": "tools/documents/normalize_markdown_emoji.py",
            "category": "documents",
            "description": "Normalize markdown heading emoji markers, with check mode for task verification.",
            "input": {
                "required": [],
                "optional": [
                    "-Paths",
                    "-DefaultEmoji",
                    "-Check"
                ],
                "rule": "Run from the repository root and prefer wrapper scripts over internal engines for normal document edits."
            },
            "output": {
                "success": "Completes the document operation or check and prints the requested result or OK status.",
                "failure": "Throws or exits nonzero when paths, selectors, duplicate policy, schema rules, normalization, or post-edit checks fail."
            }
        },
        "normalize_text_files.py": {
            "path": "tools/text/normalize_text_files.py",
            "category": "text",
            "description": "Normalize repository text file line endings and final newlines with Python, including check mode support.",
            "input": {
                "required": [],
                "optional": [
                    "paths",
                    "--repo-root",
                    "--check"
                ],
                "rule": "Run from the repository root when checking or normalizing repository text files."
            },
            "output": {
                "success": "Prints OK when files are already normalized or lists normalized files.",
                "failure": "Exits nonzero when files cannot be read/written or check mode finds stale normalization."
            }
        },
        "open_pipeline_learning_issue.py": {
            "path": "tools/repo/open_pipeline_learning_issue.py",
            "category": "repo",
            "description": "Open or print a GitHub issue request for pipeline learning discovered in a child project.",
            "input": {
                "required": [
                    "-ProjectPath"
                ],
                "optional": [
                    "-SourceFeatureListPath",
                    "-Owner",
                    "-Repo",
                    "-IssueTitle",
                    "-LearnedSummary",
                    "-ChangedScripts",
                    "-ReporterInstruction",
                    "-ExcludePatterns",
                    "-Open"
                ],
                "rule": "Run from the repository root as part of task, git, learning, or repository health workflows."
            },
            "output": {
                "success": "Completes the repository workflow step and exits 0 when the requested operation succeeds.",
                "failure": "Throws or exits nonzero when required inputs, repository state, external tooling, or workflow checks fail."
            }
        },
        "pipeline_bootstrap_index.py": {
            "path": "tools/pipeline/pipeline_bootstrap_index.py",
            "category": "pipeline",
            "description": "Internal engine for building the pipeline bootstrap index from source document catalogs.",
            "input": {
                "required": [],
                "optional": [
                    "--repo-root",
                    "--output",
                    "--documents",
                    "--check"
                ],
                "rule": "Run from the repository root or an explicit target path when initializing, syncing, compiling, or migrating pipeline packages."
            },
            "output": {
                "success": "Completes the pipeline operation and writes, checks, or prints the requested pipeline artifact.",
                "failure": "Throws or exits nonzero when inputs are invalid, target paths are unsafe, generated artifacts are stale, or pipeline checks fail."
            }
        },
        "chain_runner.py": {
            "path": "tools/chains/chain_runner.py",
            "category": "chains",
            "description": "Shared runner and structured result contract for SocratexPipeline command chains.",
            "input": {
                "required": [],
                "optional": [
                    "--self-test-failure",
                    "--expect-failure",
                    "--dry-run",
                    "--keep-going",
                    "--report-path"
                ],
                "rule": "Use concrete chain entrypoints for normal work; --self-test-failure exists only to verify the structured failure contract."
            },
            "output": {
                "success": "Prints each underlying command and writes an optional socratex-chain-report/v1 JSON report.",
                "failure": "Returns nonzero when a required chain step fails and reports command, cwd, exit code, and recovery hint."
            }
        },
        "child_sync_smoke.py": {
            "path": "tools/chains/child_sync_smoke.py",
            "category": "chains",
            "description": "Run the child package sync and runtime-gate smoke chain.",
            "input": {
                "required": [
                    "--source-root",
                    "--project-root"
                ],
                "optional": [
                    "--install-root",
                    "--profile",
                    "--apply-sync",
                    "--dry-run",
                    "--keep-going",
                    "--report-path"
                ],
                "rule": "Sync dry-runs by default inside the chain unless --apply-sync is passed; --dry-run previews the chain itself."
            },
            "output": {
                "success": "Reports managed package sync and child runtime-gate status.",
                "failure": "Returns nonzero with a structured step report when sync or runtime verification fails."
            }
        },
        "context_bootstrap_load.py": {
            "path": "tools/chains/context_bootstrap_load.py",
            "category": "chains",
            "description": "Run the compiled-context bootstrap and STATE read chain.",
            "input": {
                "required": [],
                "optional": [
                    "--repo-root",
                    "--dry-run",
                    "--keep-going",
                    "--report-path"
                ],
                "rule": "Use after entering a project that requires compiled context before code work."
            },
            "output": {
                "success": "Reads bootstrap and STATE compiled context entries through the project reader.",
                "failure": "Returns nonzero with recovery hints for stale or missing compiled context."
            }
        },
        "final_runtime_gate.py": {
            "path": "tools/chains/final_runtime_gate.py",
            "category": "chains",
            "description": "Run the final feature-contract, no-legacy-shell, and git-clean runtime gate chain.",
            "input": {
                "required": [],
                "optional": [
                    "--repo-root",
                    "--dry-run",
                    "--keep-going",
                    "--report-path"
                ],
                "rule": "Use near the end of a pipeline task when final cleanliness and runtime-retirement status need one named command."
            },
            "output": {
                "success": "Reports feature contract, runtime gate, and git diff status.",
                "failure": "Returns nonzero with a structured failed-step report."
            }
        },
        "helper_refactor_smoke.py": {
            "path": "tools/chains/helper_refactor_smoke.py",
            "category": "chains",
            "description": "Run the standard helper-refactor smoke chain.",
            "input": {
                "required": [],
                "optional": [
                    "--repo-root",
                    "--dry-run",
                    "--keep-going",
                    "--report-path"
                ],
                "rule": "Use after shared helper/script extraction to compile key files and run feature/runtime contracts."
            },
            "output": {
                "success": "Reports syntax, feature contract, and runtime-gate status.",
                "failure": "Returns nonzero with command, cwd, exit code, and recovery hint for the first required failure."
            }
        },
        "no_legacy_shell_verification.py": {
            "path": "tools/chains/no_legacy_shell_verification.py",
            "category": "chains",
            "description": "Run the no-legacy-shell verification chain.",
            "input": {
                "required": [],
                "optional": [
                    "--repo-root",
                    "--dry-run",
                    "--keep-going",
                    "--report-path"
                ],
                "rule": "Use as a named chain when only the script runtime retirement gate is needed."
            },
            "output": {
                "success": "Reports no-legacy-shell runtime gate status.",
                "failure": "Returns nonzero with blocked file/reference examples and a recovery hint."
            }
        },
        "pipeline_sweep.py": {
            "path": "tools/pipeline/pipeline_sweep.py",
            "category": "pipeline",
            "description": "Run the cross-project SocratexPipeline sweep upgrade and smoke runner.",
            "input": {
                "required": [],
                "optional": [
                    "-Config",
                    "-Source",
                    "-Project",
                    "-Execute",
                    "-Update",
                    "-Smoke",
                    "-Finalize",
                    "-All",
                    "-StopOnFailure",
                    "-Json",
                    "-WriteReport",
                    "-Help"
                ],
                "rule": "Dry-run is default; -Execute is required to run update, smoke, or finalizer commands. -Project accepts NAME=PATH or source:NAME=PATH."
            },
            "output": {
                "success": "Returns the per-project pass/fail/manual-attention summary and optional socratex-pipeline-sweep-report/v1 JSON.",
                "failure": "Throws when runtime resolution fails, config/project input is invalid, or any required project step fails."
            }
        },
        "source_finalization_precheck.py": {
            "path": "tools/chains/source_finalization_precheck.py",
            "category": "chains",
            "description": "Run source final-task prechecks and runtime gate as one named chain.",
            "input": {
                "required": [],
                "optional": [
                    "--repo-root",
                    "--quality",
                    "--dry-run",
                    "--keep-going",
                    "--report-path"
                ],
                "rule": "Use before source finalization when generated checks and runtime retirement should be verified before committing."
            },
            "output": {
                "success": "Reports final task checks and runtime-gate status.",
                "failure": "Returns nonzero with a structured failed-step report."
            }
        },
        "resolve_tool_runtime.py": {
            "path": "tools/pipeline/resolve_tool_runtime.py",
            "category": "pipeline",
            "description": "Resolve the required Socratex Python runtime across Windows, Linux, and Steam Deck/Linux environments without hardcoded bundled interpreter paths.",
            "input": {
                "required": [],
                "optional": [
                    "-SearchRoot",
                    "SOCRATEX_PYTHON",
                    "RIFTBOUND_PYTHON"
                ],
                "rule": "Use before Python-first pipeline tools when runtime availability is uncertain. Set SOCRATEX_PYTHON or RIFTBOUND_PYTHON to override discovery where supported."
            },
            "output": {
                "success": "Returns an executable Python 3 command path/source suitable for invocation.",
                "failure": "Throws with a concrete installation or environment-variable hint when no usable runtime is found."
            }
        },
        "resolve_workspace_root.py": {
            "path": "tools/pipeline/resolve_workspace_root.py",
            "category": "pipeline",
            "description": "Resolve the local Socratex workspace root from a workspace.json marker stored next to SocratexAI, without hardcoding work/projects/home paths.",
            "input": {
                "required": [],
                "optional": [
                    "-StartPath",
                    "-WorkspaceRoot",
                    "-Json",
                    "SOCRATEX_WORKSPACE_ROOT"
                ],
                "rule": "Use this for workspace-level operations such as sibling source checkout discovery, imports, archives, and drive exports. Project-local scripts should still resolve their own repo root relative to script location."
            },
            "output": {
                "success": "Prints the workspace root by default, or JSON with resolved workspace, projects, SocratexAI, tools, archive, drive export, and Drive URI fields when -Json is used.",
                "failure": "Throws when no workspace.json marker next to SocratexAI can be found or an explicit root is invalid."
            }
        },
        "rebuild_ai_compiled_context.py": {
            "path": "tools/pipeline/rebuild_ai_compiled_context.py",
            "category": "pipeline",
            "description": "Python generator for AI-compiled instruction files, SQLite knowledge database, and JSON knowledge-file fallback from source documents.",
            "input": {
                "required": [],
                "optional": [
                    "--repo-root",
                    "--output-dir",
                    "--packs",
                    "--check"
                ],
                "rule": "Use this as the Python-first compiled context refresh/check path; keep the legacy wrapper only until the Python-only deletion pass."
            },
            "output": {
                "success": "Refreshes or checks generated AI-compiled artifacts and prints OK when complete.",
                "failure": "Exits nonzero when source compilation, knowledge compilation, or check mode fails."
            }
        },
        "reinitialize_pipeline.py": {
            "path": "tools/pipeline/reinitialize_pipeline.py",
            "category": "pipeline",
            "description": "Reinitialize a project pipeline package from current source templates and selected packs.",
            "input": {
                "required": [],
                "optional": [
                    "-TargetPath",
                    "-Packs",
                    "-UseChangelog",
                    "-DryRun"
                ],
                "rule": "Run from the repository root or an explicit target path when initializing, syncing, compiling, or migrating pipeline packages."
            },
            "output": {
                "success": "Completes the pipeline operation and writes, checks, or prints the requested pipeline artifact.",
                "failure": "Throws or exits nonzero when inputs are invalid, target paths are unsafe, generated artifacts are stale, or pipeline checks fail."
            }
        },
        "remove_pipeline.py": {
            "path": "tools/pipeline/remove_pipeline.py",
            "category": "pipeline",
            "description": "Remove SocratexPipeline files from a target project with dry-run and restore options.",
            "input": {
                "required": [],
                "optional": [
                    "-TargetPath",
                    "-DirectiveFiles",
                    "-RestoreOldDirectives",
                    "-RemoveLocalWorkingFiles",
                    "-DryRun"
                ],
                "rule": "Run from the repository root or an explicit target path when initializing, syncing, compiling, or migrating pipeline packages."
            },
            "output": {
                "success": "Completes the pipeline operation and writes, checks, or prints the requested pipeline artifact.",
                "failure": "Throws or exits nonzero when inputs are invalid, target paths are unsafe, generated artifacts are stale, or pipeline checks fail."
            }
        },
        "repair_mojibake.py": {
            "path": "tools/text/repair_mojibake.py",
            "category": "text",
            "description": "Repair common mojibake text corruption in selected files with Python, including check mode support.",
            "input": {
                "required": [],
                "optional": [
                    "paths",
                    "--repo-root",
                    "--check"
                ],
                "rule": "Run from the repository root when checking or repairing repository text files."
            },
            "output": {
                "success": "Prints OK when no repairs are needed or lists repaired files.",
                "failure": "Exits nonzero when files cannot be read/written or check mode finds needed repairs."
            }
        },
        "report_pipeline_learning.py": {
            "path": "tools/repo/report_pipeline_learning.py",
            "category": "repo",
            "description": "Generate a pipeline learning report from changed child-project artifacts.",
            "input": {
                "required": [
                    "-ProjectPath"
                ],
                "optional": [
                    "-SourceFeatureListPath",
                    "-ExcludePatterns",
                    "-OutputPath"
                ],
                "rule": "Run from the repository root as part of task, git, learning, or repository health workflows."
            },
            "output": {
                "success": "Completes the repository workflow step and exits 0 when the requested operation succeeds.",
                "failure": "Throws or exits nonzero when required inputs, repository state, external tooling, or workflow checks fail."
            }
        },
        "run_quality_fix.py": {
            "path": "tools/quality/run_quality_fix.py",
            "category": "quality",
            "description": "Run repository quality fix steps that can safely repair generated or normalized artifacts.",
            "input": {
                "required": [],
                "optional": [],
                "rule": "Run from the repository root as part of task verification or quality repair workflows."
            },
            "output": {
                "success": "Completes the quality fix/check operation and exits 0 when selected work succeeds.",
                "failure": "Throws or exits nonzero when selected quality repair or verification cannot complete."
            }
        },
        "run_quality_gate.py": {
            "path": "tools/quality/run_quality_gate.py",
            "category": "quality",
            "description": "Python-first repository quality gate entrypoint that runs QUALITY-GATE.json, a named command subset, an explicit command, or standard project fallback tests.",
            "input": {
                "required": [],
                "optional": [
                    "--repo-root",
                    "--command",
                    "--command-names",
                    "--skip"
                ],
                "rule": "Use this as the canonical quality gate entrypoint for Python-first finalizers. Prefer --command-names for focused QUALITY-GATE.json subsets and --command only for explicit ad hoc commands."
            },
            "output": {
                "success": "Runs the selected quality command or contract and exits 0 when all selected checks pass.",
                "failure": "Exits nonzero when the explicit command, QUALITY-GATE command, or detected fallback test command fails."
            }
        },
        "run_quality_gate_contract.py": {
            "path": "tools/quality/run_quality_gate_contract.py",
            "category": "quality",
            "description": "Python-first executor for the repository QUALITY-GATE.json command contract.",
            "input": {
                "required": [],
                "optional": [
                    "--path",
                    "--repo-root",
                    "--command-names"
                ],
                "rule": "Run without arguments from the repository root to execute QUALITY-GATE.json. Pass --command-names with comma-separated or repeated keys to run a focused subset."
            },
            "output": {
                "success": "Runs every selected quality-gate command and exits 0 after printing OK.",
                "failure": "Exits nonzero when the contract is missing, a command key is unknown, command text is empty, or any selected command exits nonzero."
            }
        },
        "set_directives.py": {
            "path": "tools/pipeline/set_directives.py",
            "category": "pipeline",
            "description": "Apply, merge, or replace top-level directive files in a target pipeline installation.",
            "input": {
                "required": [],
                "optional": [
                    "-Mode",
                    "-TargetPath",
                    "-DirectiveFiles"
                ],
                "rule": "Run from the repository root or an explicit target path when initializing, syncing, compiling, or migrating pipeline packages."
            },
            "output": {
                "success": "Completes the pipeline operation and writes, checks, or prints the requested pipeline artifact.",
                "failure": "Throws or exits nonzero when inputs are invalid, target paths are unsafe, generated artifacts are stale, or pipeline checks fail."
            }
        },
        "sync_pipeline_featurelist.py": {
            "path": "tools/repo/sync_pipeline_featurelist.py",
            "category": "repo",
            "description": "Python-first instance pipeline_featurelist.json synchronizer from source feature manifests.",
            "input": {
                "required": [],
                "optional": [
                    "--target-path",
                    "--source-feature-list-path",
                    "--output-path",
                    "--pipeline-id",
                    "--extra-features",
                    "--dry-run"
                ],
                "rule": "Run after installed package updates so child projects can compare their local feature set against the source feature list."
            },
            "output": {
                "success": "Writes or prints the instance feature list and reports same/missing/extra counts.",
                "failure": "Exits nonzero when the source feature list is missing, empty, or invalid."
            }
        },
        "task_snapshot.py": {
            "path": "tools/repo/task_snapshot.py",
            "category": "repo",
            "description": "Python-first compact task snapshot for repository finalization workflows.",
            "input": {
                "required": [],
                "optional": [
                    "--root",
                    "--max-lines",
                    "--no-git"
                ],
                "rule": "Use during Pass 0S as the Python replacement for task snapshot reporting."
            },
            "output": {
                "success": "Prints branch, last commit, status, diff summaries, untracked files, and known task document line counts.",
                "failure": "Exits nonzero when repository inspection fails."
            }
        },
        "task_flow_audit.py": {
            "path": "tools/repo/task_flow_audit.py",
            "category": "repo",
            "description": "Python-first task-flow closure checklist and conditional complex-task adversarial review prompt.",
            "input": {
                "required": [],
                "optional": [
                    "--paths",
                    "--project-root",
                    "--changelog-path",
                    "--complex",
                    "--no-changelog",
                    "--require-closure-evidence",
                    "--closure-evidence-path"
                ],
                "rule": "Use during Pass 0S as the Python replacement for task_flow_audit.py; pass --project-root when invoking a managed package copy from a child project."
            },
            "output": {
                "success": "Prints required closure artifacts, latest changelog evidence when present, complex-task adversarial review prompts when applicable, and validates closure evidence when required.",
                "failure": "Exits nonzero when git or changelog parsing fails, required evidence is missing, or evidence lacks required closure fields."
            }
        },
        "update_code_line_index.py": {
            "path": "tools/codebase/update_code_line_index.py",
            "category": "codebase",
            "description": "Refresh or check docs-tech/CODE_LINE_INDEX.json and docs-tech/LARGE_FILES.json through Python.",
            "input": {
                "required": [],
                "optional": [
                    "--index-path",
                    "--large-files-path",
                    "--large-file-threshold",
                    "--paths",
                    "--root",
                    "--changed-only",
                    "--check"
                ],
                "rule": "Use during Pass 0S as the Python replacement for code line index refresh. Use --changed-only for normal task closure and --check to fail on stale indexes."
            },
            "output": {
                "success": "Writes or verifies the code line index and generated large-file document, then prints indexed file counts.",
                "failure": "Exits nonzero when git/path discovery fails or check mode finds stale generated indexes."
            }
        },
        "update_pipeline_from_link.py": {
            "path": "tools/pipeline/update_pipeline_from_link.py",
            "category": "pipeline",
            "description": "Python-first updater for installed SocratexAI packages from local path, zip URL, or shallow Git source.",
            "input": {
                "required": [
                    "--source"
                ],
                "optional": [
                    "--target-path",
                    "--source-mode",
                    "--git-ref",
                    "--packs",
                    "--profile",
                    "--directive-mode",
                    "--directive-files",
                    "--reinitialize-new",
                    "--full-verify",
                    "--dry-run"
                ],
                "rule": "Default mode is cheap: managed package mirror, featurelist sync, directive refresh, and Python feature-contract check. Use --full-verify only for heavier post-update verification."
            },
            "output": {
                "success": "Mirrors managed SocratexAI paths, preserves project-owned files, runs cheap checks, and reports skipped full verification unless --full-verify was used.",
                "failure": "Exits nonzero on unresolved source, unsafe sync, failed directive update, failed feature-contract check, or failed full verification."
            }
        },
        "upgrade_from_reference_project.py": {
            "path": "tools/pipeline/upgrade_from_reference_project.py",
            "category": "pipeline",
            "description": "Upgrade a target project from a reference project pipeline snapshot.",
            "input": {
                "required": [
                    "-ReferenceProjectPath"
                ],
                "optional": [
                    "-TargetPath",
                    "-DryRun"
                ],
                "rule": "Run from the repository root or an explicit target path when initializing, syncing, compiling, or migrating pipeline packages."
            },
            "output": {
                "success": "Completes the pipeline operation and writes, checks, or prints the requested pipeline artifact.",
                "failure": "Throws or exits nonzero when inputs are invalid, target paths are unsafe, generated artifacts are stale, or pipeline checks fail."
            }
        },
        "utf8_file_helpers.py": {
            "path": "tools/text/utf8_file_helpers.py",
            "category": "text",
            "description": "Provide reusable UTF-8 file read/write helpers for Python scripts.",
            "input": {
                "required": [],
                "optional": [],
                "rule": "Import from Python text utilities instead of duplicating UTF-8 and line-ending logic."
            },
            "output": {
                "success": "Provides helper functions for UTF-8 reads, writes, and line-ending conversion.",
                "failure": "Raises Python exceptions for invalid line-ending modes or file IO errors."
            }
        },
        "run_interactive_setup.py": {
            "path": "tools/setup/run_interactive_setup.py",
            "category": "setup",
            "description": "Run the interactive setup flow or dry-run it for verification.",
            "input": {
                "required": [],
                "optional": [
                    "-DryRun"
                ],
                "rule": "Run from the repository root or setup target when checking host/runtime setup."
            },
            "output": {
                "success": "Completes setup probing or configuration and prints the resulting setup status.",
                "failure": "Throws or exits nonzero when runtime detection or requested setup configuration fails."
            }
        },
        "write_utf8_file.py": {
            "path": "tools/text/write_utf8_file.py",
            "category": "text",
            "description": "Write text through the repository UTF-8 helper with line-ending and newline controls using Python.",
            "input": {
                "required": [
                    "--path"
                ],
                "optional": [
                    "--value",
                    "--no-newline",
                    "--line-ending",
                    "stdin"
                ],
                "rule": "Use --value for simple values and stdin for multiline content."
            },
            "output": {
                "success": "Writes the target file as UTF-8 without BOM and prints OK.",
                "failure": "Exits nonzero when the target cannot be written."
            }
        },
        "sync_managed_pipeline_package.py": {
            "path": "tools/pipeline/sync_managed_pipeline_package.py",
            "category": "pipeline",
            "description": "Python-first managed SocratexAI package mirror for source-owned package paths inside child projects.",
            "input": {
                "required": [
                    "--source-root",
                    "--install-root"
                ],
                "optional": [
                    "--project-root",
                    "--profile",
                    "--managed-paths",
                    "--child-generated-paths",
                    "--protected-paths",
                    "--apply-project-profile",
                    "--prune-unmanaged",
                    "--force-managed",
                    "--dry-run"
                ],
                "rule": "Use only for source-owned SocratexAI package paths; project memory and configuration outside SocratexAI remain child-owned."
            },
            "output": {
                "success": "Writes package manifest, reports preserved local overrides, and prints OK when complete.",
                "failure": "Exits nonzero on unsafe paths, missing profile files, invalid manifests, or copy/remove failures."
            }
        },
        "read_compiled_context.py": {
            "path": "tools/pipeline/read_compiled_context.py",
            "category": "pipeline",
            "description": "Read a source compiled instruction file or a compact source context document by alias with Python-only tooling.",
            "input": {
                "required": [
                    "document"
                ],
                "optional": [
                    "--compiled-root",
                    "--allow-stale",
                    "--json"
                ],
                "rule": "Prefer this Python reader for Python-only source context reads during the runtime retirement pass."
            },
            "output": {
                "success": "Compiled or source context content by default, or JSON with selected path and content when --json is used.",
                "failure": "Exits nonzero when no alias/path matches or when a compiled output hash is stale."
            }
        },
        "tool_error_log.py": {
            "path": "tools/pipeline/tool_error_log.py",
            "category": "pipeline",
            "description": "Append a tool invocation or result-contract failure to docs-tech/TOOL-ERRORS.json, defaulting to the parent project registry when running from an installed SocratexAI package.",
            "input": {
                "required": [],
                "optional": [
                    "-Path",
                    "-Key",
                    "-Title",
                    "-Status",
                    "-Tool",
                    "-Failure",
                    "-FailingCommandShape",
                    "-ObservedError",
                    "-SuspectedContractGap",
                    "-FixTarget",
                    "-DetailsJson",
                    "-DetailsJsonFile",
                    "-ObservedAt",
                    "-Json"
                ],
                "rule": "Omit -Path for the default tool-error registry. Use -DetailsJsonFile for nested, multiline, or quote-heavy payloads; valid JSON is stored as structured data and invalid JSON is stored as text."
            },
            "output": {
                "success": "OK text or JSON with the inserted key and target path.",
                "failure": "Throws if the registry cannot be initialized or the entry cannot be appended."
            }
        },
        "tool_handler.py": {
            "path": "tools/pipeline/tool_handler.py",
            "category": "pipeline",
            "description": "Public single entry point for repository tool operations; validates inputs, normalizes parameters and aliases, delegates to the target script, logs input errors, and returns a stable result envelope.",
            "input": {
                "required": [
                    "-Operation"
                ],
                "optional": [
                    "-ParametersJson",
                    "-ParametersJsonFile",
                    "-OutputMode",
                    "-ErrorLogPath",
                    "-NoErrorLog"
                ],
                "rule": "Use exactly one of -ParametersJson or -ParametersJsonFile. Prefer -ParametersJsonFile for nested, multiline, or quote-heavy parameter payloads."
            },
            "output": {
                "success": "Structured result envelope with ok=true, normalized operation, target script, normalized parameters, command, exit code, and captured output.",
                "failure": "Structured result envelope with ok=false, error type/message, and logged_error_key when validation logged an input failure."
            }
        },
        "project_design_context.py": {
            "path": "tools/knowledge/project_design_context.py",
            "category": "knowledge",
            "description": "Read project-specific code_design_required_reads from PIPELINE-CONFIG.json, print the project's design context, and write ignored/project_design_context_gate.json so downstream task checks can prove the design rules were loaded for the current HEAD.",
            "input": {
                "required": [],
                "optional": [
                    "-ProjectRoot",
                    "-Quiet"
                ],
                "rule": "Run from the project root or pass -ProjectRoot. The script no-ops cleanly when code_design_required_reads is absent."
            },
            "output": {
                "success": "Writes ignored/project_design_context_gate.json with declared and loaded design-context files for HEAD.",
                "failure": "Throws when PIPELINE-CONFIG.json is missing or one of the declared design-context files cannot be read."
            }
        },
        "check_project_design_context_gate.py": {
            "path": "tools/codebase/check_project_design_context_gate.py",
            "category": "codebase",
            "description": "Verify ignored/project_design_context_gate.json was refreshed for the current HEAD and changed code paths, so finalize/task-check flows can prove the project's design rules were loaded before code edits.",
            "input": {
                "required": [],
                "optional": [
                    "-ProjectRoot",
                    "-Paths",
                    "-MaxAgeMinutes"
                ],
                "rule": "Pass changed paths when checking a focused task; omit paths to derive them from git working tree + staged + untracked."
            },
            "output": {
                "success": "Confirms the gate file exists, matches current HEAD, and covers the changed code paths.",
                "failure": "Throws when the gate is missing, stale relative to HEAD or MaxAgeMinutes, or does not cover the declared design-context reads."
            }
        },
        "json_wrapper_entrypoints.py": {
            "path": "tools/json/json_wrapper_entrypoints.py",
            "category": "json",
            "description": "Shared Python implementation for native JSON wrapper entrypoints.",
            "input": {
                "required": [],
                "optional": [],
                "rule": "Internal module imported by json_*.py wrappers; use the wrapper scripts directly."
            },
            "output": {
                "success": "Routes wrapper arguments to json_list_doc.py with Python-only tooling.",
                "failure": "Raises or exits nonzero when wrapper arguments or JSON document operations fail."
            }
        },
        "gpt_shared_conversation_extract.py": {
            "path": "tools/adapters/gpt_shared_conversation_extract.py",
            "category": "adapters",
            "description": "Extract visible user/assistant messages from a public ChatGPT shared conversation page into Markdown or JSON while preserving Markdown tables, emoji, lists, and code blocks.",
            "input": {
                "required": [
                    "one of positional URL, --url/-Url, or --input-file/-InputFile"
                ],
                "optional": [
                    "--output/-Output",
                    "--format/-Format markdown|json",
                    "--timeout/-Timeout",
                    "--no-metadata/-NoMetadata",
                    "--include-technical-user-messages/-IncludeTechnicalUserMessages",
                    "--assistant-mode/-AssistantMode"
                ],
                "rule": "Use when the user provides a public chatgpt.com/share URL or saved share HTML and asks to read, summarize, analyze, or reuse that conversation. Prefer this extractor before feeding page HTML into the model."
            },
            "output": {
                "success": "Writes clean extracted conversation Markdown by default, or JSON with title, source, counts, skipped technical entries, and visible messages.",
                "failure": "Exits nonzero when the page cannot be fetched, the React Router stream cannot be decoded, or no conversation data is found."
            }
        },
        "gpt_conversation_archive.py": {
            "path": "tools/adapters/gpt_conversation_archive.py",
            "category": "adapters",
            "description": "List, search, normalize, and read local ChatGPT conversation exports or generated conversation archives without requiring private account/session access.",
            "input": {
                "required": [
                    "subcommand: list, search, read, or index",
                    "--source/-Source"
                ],
                "optional": [
                    "--query/-Query",
                    "--project/-Project",
                    "--conversation-id/-ConversationId",
                    "--position/-Position",
                    "--title-contains/-TitleContains",
                    "--limit/-Limit",
                    "--format/-Format",
                    "--output/-Output",
                    "--any-term/-AnyTerm",
                    "--no-metadata/-NoMetadata",
                    "--assistant-mode/-AssistantMode"
                ],
                "rule": "Use when the user asks to search or read private ChatGPT conversations from a local export/cache. Do not use this as live account scraping; the source must be an explicit local file or directory supplied by the user/workspace."
            },
            "output": {
                "success": "For list/search, prints compact text or JSON candidates. For read, emits one clean conversation in Markdown or JSON. For index, writes reusable normalized archive JSON.",
                "failure": "Exits nonzero when the source is missing, unsupported, or a selector matches no or multiple conversations."
            }
        }
    },
    "metadata": {
        "document": {
            "title": "Source Pipeline Script Index",
            "type": "script_index",
            "language": "en"
        },
        "context_loading": {
            "default": "index_only",
            "content_read": "only when exact metadata for a specific script is needed"
        },
        "script_io_contract": {
            "purpose": "Describe stable invocation contracts for scripts whose argument shape is not obvious from the script name alone.",
            "default_context_rule": "The default SCRIPTS context remains name/index-only; read input/output only before invoking a script whose argument shape is not obvious.",
            "structured_json_rule": "For long, multiline, nested, or quote-heavy JSON, prefer file/stdin value inputs over inline shell arguments. For order-only or structural JSON changes, use json_node_edit.py or narrower JSON wrappers instead of manual patching."
        },
        "categories": {
            "documents": [
                "audit_docs.py",
                "audit_docs.py",
                "build_document_cache.py",
                "build_document_cache.py",
                "document_item_edit_engine.py",
                "bulk_insert_document_items.py",
                "insert_document_item.py",
                "migrate_document_item.py",
                "move_document_item.py",
                "list_document_keys.py",
                "check_document_list_item_duplicates.py",
                "insert_document_list_item.py",
                "insert_checked_document_list_item.py",
                "document_list_item_edit_engine.py",
                "review_document_list_candidates.py",
                "run_document_post_edit_checks.py",
                "read_document_item.py",
                "read_document_items_by_title.py",
                "document_read_cache_engine.py",
                "migrate_document_schema.py",
                "document_schema_migration_engine.py",
                "normalize_document_structure.py",
                "document_structure_normalizer_engine.py",
                "normalize_markdown_emoji.py"
            ],
            "knowledge": [
                "context_tags.py",
                "context_tags.py",
                "knowledge_check.py",
                "knowledge_check.py",
                "knowledge_code_context.py",
                "knowledge_code_context.py",
                "knowledge_compile.py",
                "knowledge_compile.py",
                "knowledge_delete.py",
                "knowledge_delete.py",
                "knowledge_file_check.py",
                "knowledge_file_check.py",
                "knowledge_file_compile.py",
                "knowledge_file_compile.py",
                "knowledge_file_delete.py",
                "knowledge_file_delete.py",
                "knowledge_file_query.py",
                "knowledge_file_query.py",
                "knowledge_file_rename.py",
                "knowledge_file_rename.py",
                "knowledge_file_select.py",
                "knowledge_file_select.py",
                "knowledge_file_upsert.py",
                "knowledge_file_upsert.py",
                "knowledge_index.py",
                "knowledge_tier_report.py",
                "knowledge_tier_check.py",
                "knowledge_query.py",
                "knowledge_query.py",
                "knowledge_rename.py",
                "knowledge_rename.py",
                "knowledge_select.py",
                "knowledge_select.py",
                "knowledge_upsert.py",
                "knowledge_upsert.py"
            ],
            "repo": [
                "add_changelog_entry.py",
                "check_pipeline_featurelist_update.py",
                "check_pipeline_feature_contracts.py",
                "sync_pipeline_featurelist.py",
                "check_sensitive_reference_leaks.py",
                "check_sensitive_reference_leaks.py",
                "check_task.py",
                "check_toolchain_health.py",
                "legacy_commit_task_compatibility_wrapper.py",
                "finalize_task_check_commit_push.py",
                "finalize_changed_files_commit_push.py",
                "finalize_changed_files_commit_push.py",
                "run_final_task_checks.py",
                "run_final_task_checks.py",
                "end_prompt_snapshot.py",
                "end_prompt_snapshot.py",
                "task_snapshot.py",
                "task_snapshot.py",
                "task_flow_audit.py",
                "task_flow_audit.py",
                "learn_pipeline_features.py",
                "open_pipeline_learning_issue.py",
                "report_pipeline_learning.py",
                "sync_pipeline_featurelist.py"
            ],
            "pipeline": [
                "check_ai_compiled_context.py",
                "check_ai_compiled_context.py",
                "python_runtime.py",
                "pipeline_package.py",
                "compile_pipeline_context.py",
                "update_pipeline_from_link.py",
                "sync_managed_pipeline_package.py",
                "compile_pipeline_context.py",
                "generate_installed_agent_instructions.py",
                "generate_embedded_config_payload.py",
                "import_existing_project.py",
                "init_branch_memory.py",
                "init_task_work.py",
                "Initialize-SocratexPipeline.py",
                "Initialize-SocratexPipeline.py",
                "migrate_ai_pipeline.py",
                "pipeline_bootstrap_index.py",
                "pipeline_bootstrap_index.py",
                "resolve_tool_runtime.py",
                "resolve_workspace_root.py",
                "rebuild_ai_compiled_context.py",
                "rebuild_ai_compiled_context.py",
                "reinitialize_pipeline.py",
                "remove_pipeline.py",
                "set_directives.py",
                "update_pipeline_from_link.py",
                "upgrade_from_reference_project.py",
                "sync_managed_pipeline_package.py",
                "tool_handler.py",
                "tool_error_log.py",
                "read_compiled_context.py",
                "read_compiled_context.py"
            ],
            "setup": [
                "detect_project_stack.py",
                "run_interactive_setup.py"
            ],
            "text": [
                "check_utf8_writes.py",
                "normalize_documents.bat",
                "normalize_json_files.py",
                "normalize_json_files.py",
                "normalize_text_files.py",
                "normalize_text_files.py",
                "repair_mojibake.py",
                "repair_mojibake.py",
                "utf8_file_helpers.py",
                "utf8_file_helpers.py",
                "write_utf8_file.py",
                "write_utf8_file.py"
            ],
            "quality": [
                "check_evals.py",
                "check_evals.py",
                "check_python_syntax.py",
                "check_runtime.py",
                "run_quality_fix.py",
                "run_quality_gate.py",
                "run_quality_gate.py",
                "run_quality_gate_contract.py",
                "run_quality_gate_contract.py"
            ],
            "diagnostics": [
                "console_summary.py",
                "log_summary.py"
            ],
            "codebase": [
                "check_code_context_gate.py",
                "update_code_line_index.py",
                "update_code_line_index.py"
            ],
            "json": [
                "audit_json_docs.py",
                "json_list_doc.py",
                "json_wrapper_entrypoints.py",
                "json_refresh_index.py",
                "json_refresh_index.py",
                "json_migrate_content.py",
                "json_migrate_content.py",
                "json_node_edit.py",
                "json_node_edit.py",
                "json_read.py",
                "json_read.py",
                "json_item_insert.py",
                "json_item_insert.py",
                "json_item_set.py",
                "json_item_set.py",
                "json_item_move.py",
                "json_item_move.py",
                "json_item_delete.py",
                "json_item_delete.py",
                "json_line_insert.py",
                "json_line_insert.py",
                "json_line_set.py",
                "json_line_set.py",
                "json_line_move.py",
                "json_line_move.py",
                "smoke_json_tools.py"
            ]
        },
        "category_rule": "Scripts live under tools/<category>/ and SCRIPTS.json keeps the filename index plus exact categorized path for execution."
    }
}