feat: confluence benchmark, pattern extractor, agent KB, UX spec

- extract-patterns.js: mines layered arch, ArgoCD appsets, cloud regions,
  CIDR allocations, naming conventions, sync waves, tech stack from code
- agent-kb.js: token-efficient JSON rendering of same doc tree
- eval-confluence-ref-questions.json: 32 reference-only benchmark questions
- wiggum-v2.sh: Ralph Wiggum loop targeting confluence baseline (77.8%)
- docs/human-ux-spec.md: BMad UX designer spec for human doc structure
- Eval results: V2 at 28.7% vs confluence 77.8% baseline
- Hub/spoke ownership now correctly extracted (95% on that question)
- Naming conventions, regions, CIDRs surfaced in system-architecture.md

foxtrot-docs-v3/reference/subsystems/account-common.md

@@ -0,0 +1,10 @@
+# Subsystem: account-common
+
+**Kind:** domain
+**Files:** 8
+**Functions:** 0, **Classes:** 0
+
+## Structural Notes
+- Zero functions despite 8 files — likely a configuration-only or IaC subsystem
+- Isolated subsystem with no cross-subsystem dependencies — may be self-contained tooling or unused
+

foxtrot-docs-v3/reference/subsystems/app-common.md

@@ -0,0 +1,38 @@
+# Subsystem: app-common
+
+**Kind:** domain
+**Files:** 934
+**Functions:** 28, **Classes:** 0
+
+## Dependencies
+### Depends On
+- → app-tools: 1 calls, 0 imports
+
+## Public Exports
+- `add_bucket_policy`
+- `add_destination_to_lambda_function`
+- `add_resource_based_policy_to_lambda_function`
+- `check_certificate_exists`
+- `create_lambda_function`
+- `create_or_get_gateway`
+- `delete_lambda_function`
+- `ensure_s3_bucket_exists`
+- `find_app_namespaces`
+- `find_application_jar`
+- `generate_certificate`
+- `generate_placeholder_certificate`
+- `get_aws_account_id`
+- `get_cloud_config`
+- `handle_error`
+- `load_compute_config`
+- `load_kong_config`
+- `log_error`
+- `log_info`
+- `main`
+- `make_request`
+- `read_file_content`
+- `update_bucket_notification_configuration`
+- `upload_certificate`
+- `upload_properties_files`
+- `with_delay`
+- `write_file_content`

foxtrot-docs-v3/reference/subsystems/app-tools.md

@@ -0,0 +1,73 @@
+# Subsystem: app-tools
+
+**Kind:** cross-cutting
+**Files:** 17
+**Functions:** 92, **Classes:** 4
+
+## Dependencies
+### Depended On By
+- ← app-common: 1 calls, 0 imports
+- ← compute-tools: 4 calls, 0 imports
+- ← ipam-tools: 6 calls, 0 imports
+
+## Public Exports
+- `Config`
+- `EnvExporter`
+- `FILES_TO_COPY`
+- `GitManager`
+- `cleanup`
+- `clone_repo`
+- `commit_and_push_changes`
+- `create_ak_sk`
+- `create_ak_sk_for_dph_user`
+- `create_ak_sk_for_es_user`
+- `create_ak_sk_for_export_user`
+- `create_aurora_mysql_db`
+- `create_db_subnet_group`
+- `create_gcp_bq_services`
+- `create_gcp_project`
+- `create_kms_key`
+- `create_rdm_gcp_bq_services`
+- `create_s3_buckets`
+- `create_security_group`
+- `display_help`
+- `emit_exports`
+- `enable_api_and_wait`
+- `enable_project_apis`
+- `ensure_gcs_bucket_exists`
+- `ensure_s3_bucket_exists`
+- `format_seconds`
+- `gcp_project_exists`
+- `generate_strong_password`
+- `get_aws_account_number`
+- `get_env_vars`
+- `get_matching_user`
+- `get_projects`
+- `get_rdm_mdm_companions`
+- `get_sensitive_input`
+- `get_verified_gcs_client`
+- `get_verified_s3_client`
+- `handle_api_error`
+- `list_private_subnets`
+- `list_rds_subnet_groups`
+- `log_error`
+- `log_exception`
+- `log_info`
+- `log_step`
+- `main`
+- `patch_crossaccount_mdm_companions`
+- `patch_mdm_policy_rdm_companion_arn`
+- `patch_mdm_systemdynamodb_shared_devops_api`
+- `patch_shared_devops_api_mdm_arns`
+- `patch_trust_policy_for_dataquality_snapshot`
+- `patch_vault_secret`
+- `print_summary`
+- `process_template_file`
+- `set`
+- `set_iam_policy_for_project`
+- `transfer_files`
+- `update_dynamic_secrets`
+- `update_terraform_config`
+- `vault_secret_bootstrap`
+- `wait_for_dynamodb_role`
+- `wait_for_operation`

foxtrot-docs-v3/reference/subsystems/compute-common.md

@@ -0,0 +1,24 @@
+# Subsystem: compute-common
+
+**Kind:** domain
+**Files:** 64
+**Functions:** 14, **Classes:** 0
+
+## Structural Notes
+- Isolated subsystem with no cross-subsystem dependencies — may be self-contained tooling or unused
+
+## Public Exports
+- `cleanup_tracker`
+- `helm_helper`
+- `kubectl_helper`
+- `test_aks_full_cluster_lifecycle`
+- `test_cluster_name`
+- `test_deploy_for_inspection`
+- `test_deploy_nginx_workload`
+- `test_eks_full_cluster_lifecycle`
+- `test_eks_helm_chart_renders_templates`
+- `test_eks_helm_chart_smoke`
+- `test_eks_helm_chart_validates_required_values`
+- `test_env_config`
+- `test_pod_can_resolve_dns`
+- `test_values_file`

foxtrot-docs-v3/reference/subsystems/compute-tools.md

@@ -0,0 +1,81 @@
+# Subsystem: compute-tools
+
+**Kind:** domain
+**Files:** 28
+**Functions:** 108, **Classes:** 8
+
+## Dependencies
+### Depends On
+- → app-tools: 4 calls, 0 imports
+
+### Depended On By
+- ← ipam-tools: 1 calls, 0 imports
+
+## Public Exports
+- `BritiveAuth`
+- `ClusterManager`
+- `ComputeManager`
+- `GitUtils`
+- `NamespaceManager`
+- `NetboxManager`
+- `TestAzureIPAM`
+- `VPCManager`
+- `add_files`
+- `add_region`
+- `allocate_create_vpc_cidr_blocks`
+- `allocate_vnet_registration`
+- `check_aws_cli`
+- `check_homebrew`
+- `check_kubectl`
+- `cleanup_cidrs`
+- `cli`
+- `clone_repo`
+- `commit`
+- `commit_and_push`
+- `contains_prd`
+- `create_cluster`
+- `create_namespace`
+- `create_vpc`
+- `delete_cluster`
+- `delete_cluster_config`
+- `detect_os`
+- `display_help`
+- `get_missing_params`
+- `get_next_available_azure_cidr`
+- `get_next_available_cidr`
+- `get_param`
+- `install_as_user`
+- `install_aws_cli`
+- `install_homebrew`
+- `install_uv`
+- `is_ssrv`
+- `is_state`
+- `main`
+- `mock_netbox`
+- `path`
+- `push`
+- `register_azure_vnet`
+- `register_vpc`
+- `repo_path`
+- `reserve_create_vpc_cidr_blocks`
+- `reserve_vnet_cidr_blocks`
+- `setup_and_configure`
+- `setup_cidrs`
+- `setup_cluster_config`
+- `setup_credentials`
+- `setup_namespace`
+- `setup_vpc`
+- `setup_vpc_config`
+- `show_usage`
+- `sync_vpc_to_netbox`
+- `test_allocation_failure_rollback`
+- `test_collision_retry_logic`
+- `test_idempotent_vnet_allocation`
+- `test_metadata_registration`
+- `test_metadata_update`
+- `test_no_partial_state`
+- `test_output_format`
+- `test_subnet_carve_non_overlapping`
+- `update_azure_vnet_metadata`
+- `validate_account`
+- `wait_for_deletion`

foxtrot-docs-v3/reference/subsystems/control-core.md

@@ -0,0 +1,10 @@
+# Subsystem: control-core
+
+**Kind:** domain
+**Files:** 336
+**Functions:** 0, **Classes:** 0
+
+## Structural Notes
+- Zero functions despite 336 files — likely a configuration-only or IaC subsystem
+- Isolated subsystem with no cross-subsystem dependencies — may be self-contained tooling or unused
+

foxtrot-docs-v3/reference/subsystems/ipam-core.md

@@ -0,0 +1,12 @@
+# Subsystem: ipam-core
+
+**Kind:** domain
+**Files:** 24
+**Functions:** 1, **Classes:** 1
+
+## Structural Notes
+- Isolated subsystem with no cross-subsystem dependencies — may be self-contained tooling or unused
+
+## Public Exports
+- `AuthFailed`
+- `map_groups`

foxtrot-docs-v3/reference/subsystems/ipam-tools.md

@@ -0,0 +1,63 @@
+# Subsystem: ipam-tools
+
+**Kind:** domain
+**Files:** 17
+**Functions:** 104, **Classes:** 10
+
+## Dependencies
+### Depends On
+- → app-tools: 6 calls, 0 imports
+- → compute-tools: 1 calls, 0 imports
+
+## Public Exports
+- `AllocationError`
+- `NetboxAPIConfig`
+- `NetboxError`
+- `NetboxVPCAllocator`
+- `NetboxVPCRegistrar`
+- `PrefixConfig`
+- `ResourceNotFoundError`
+- `SubnetConfig`
+- `VRFConfig`
+- `ValidationError`
+- `add_missing_cidrs`
+- `add_or_update_prefix_in_netbox`
+- `allocate_prefix`
+- `checkout_britive_profile`
+- `collect_ranges`
+- `confirm_action`
+- `create_vrf`
+- `delete_orphaned_prefixes`
+- `delete_prefix_in_netbox`
+- `delete_unused_cidrs`
+- `export_ranges_to_csv`
+- `export_to_csv`
+- `fetch_azure_network_ranges`
+- `fetch_network_ranges`
+- `find_next_available_prefix`
+- `get_account_details`
+- `get_all_netbox_prefixes`
+- `get_all_subscriptions`
+- `get_aws_subnets`
+- `get_aws_vpc_cidrs`
+- `get_netbox_prefixes`
+- `get_next_available_ips`
+- `get_next_available_prefixes`
+- `get_or_create_site`
+- `get_or_create_tenant`
+- `get_or_create_vrf`
+- `get_prefix_id_from_cidr`
+- `get_regions`
+- `get_resource_groups`
+- `get_subnet_cidr_ranges`
+- `get_subnet_ranges`
+- `get_used_prefixes`
+- `get_vnet_cidr_ranges`
+- `get_vpc_ranges`
+- `identify_missing_cidrs`
+- `identify_unused_cidrs`
+- `list_projects_in_folder`
+- `log_debug`
+- `main`
+- `sanitize_slug`
+- `use_aws_credentials`

foxtrot-docs-v3/reference/subsystems/network-common.md

@@ -0,0 +1,10 @@
+# Subsystem: network-common
+
+**Kind:** domain
+**Files:** 24
+**Functions:** 0, **Classes:** 0
+
+## Structural Notes
+- Zero functions despite 24 files — likely a configuration-only or IaC subsystem
+- Isolated subsystem with no cross-subsystem dependencies — may be self-contained tooling or unused
+

foxtrot-docs-v3/reference/subsystems/network-core.md

@@ -0,0 +1,10 @@
+# Subsystem: network-core
+
+**Kind:** domain
+**Files:** 87
+**Functions:** 0, **Classes:** 0
+
+## Structural Notes
+- Zero functions despite 87 files — likely a configuration-only or IaC subsystem
+- Isolated subsystem with no cross-subsystem dependencies — may be self-contained tooling or unused
+

foxtrot-docs-v3/reference/subsystems/runtime.md

@@ -0,0 +1,79 @@
+# Subsystem: runtime
+
+**Kind:** domain
+**Files:** 16309
+**Functions:** 69, **Classes:** 0
+
+## Structural Notes
+- 69 functions with no classes — procedural/script-heavy architecture
+- Isolated subsystem with no cross-subsystem dependencies — may be self-contained tooling or unused
+
+## Public Exports
+- `ci_scripts`
+- `format_error`
+- `load_generate_name_module`
+- `load_logging_utils`
+- `load_module`
+- `load_scan_inventory_module`
+- `load_schema`
+- `manifest_file`
+- `manifest_without_name`
+- `run_script`
+- `sample_inventory`
+- `test_ci_pipeline_validation_flow`
+- `test_clone_or_update_repo_https`
+- `test_clone_or_update_repo_missing_workspace`
+- `test_clone_or_update_repo_ssh`
+- `test_clone_or_update_repo_uses_existing`
+- `test_commit_files_to_branch`
+- `test_create_pull_request_returns_url`
+- `test_deduplicate_environments`
+- `test_directories_exist`
+- `test_dockerfile_basics`
+- `test_error_logging_includes_remediation`
+- `test_extract_environment_info_invalid`
+- `test_extract_environment_info_valid`
+- `test_extract_pr_id_from_url`
+- `test_extract_spec_missing_fields`
+- `test_find_lowest_unused_index_empty`
+- `test_find_lowest_unused_index_gap`
+- `test_find_lowest_unused_index_no_gap`
+- `test_generate_app_config_contains_expected_paths`
+- `test_generate_argo_params_contains_destination`
+- `test_generate_compute_config_contains_expected_paths`
+- `test_generate_name_main_updates_manifest`
+- `test_generate_network_config_contains_expected_paths`
+- `test_gitignore_patterns_present`
+- `test_invalid_cloud_has_clear_error`
+- `test_invalid_phase_has_clear_error`
+- `test_invalid_type_has_clear_error`
+- `test_invalid_yaml_exits_one_with_clear_message`
+- `test_log_format_is_structured`
+- `test_manifest_lifecycle_new_environment`
+- `test_manifest_lifecycle_with_existing_environments`
+- `test_missing_file_returns_error`
+- `test_missing_required_field_has_clear_error`
+- `test_missing_required_field_has_line_number`
+- `test_missing_spec_cloud_has_clear_error`
+- `test_orchestrate_full_provision`
+- `test_parse_log_line`
+- `test_provision_app_calls_bitbucket`
+- `test_provision_app_requires_compute_complete`
+- `test_provision_compute_calls_bitbucket`
+- `test_provision_compute_requires_network_complete`
+- `test_provision_network_calls_bitbucket`
+- `test_required_files_exist`
+- `test_requirements_include_dependencies`
+- `test_run_inventory_scan_uses_env_file`
+- `test_save_manifest_preserves_content`
+- `test_scan_repo_for_environments`
+- `test_taskfile_has_required_tasks`
+- `test_update_manifest_adds_metadata`
+- `test_update_manifest_annotations`
+- `test_valid_manifest_passes`
+- `test_valid_yaml_exits_zero`
+- `test_wait_for_pr_merge_declined`
+- `test_wait_for_pr_merge_success`
+- `test_wait_for_pr_merge_timeout`
+- `valid_manifest`
+- `validate_manifest`