Skip to content

decisions

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

decisions

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
0000_template.md
0000_template.md
 
 
0001_macroexpand_routing.md
0001_macroexpand_routing.md
 
 
0002_phase3_exit_no_map_literal.md
0002_phase3_exit_no_map_literal.md
 
 
0003_zlinter_no_deprecated_gate.md
0003_zlinter_no_deprecated_gate.md
 
 
0004_day1_enum_reserve.md
0004_day1_enum_reserve.md
 
 
0005_dual_backend_differential_oracle.md
0005_dual_backend_differential_oracle.md
 
 
0006_wasm_ffi_defer_phase16.md
0006_wasm_ffi_defer_phase16.md
 
 
0007_type_descriptor_option_beta.md
0007_type_descriptor_option_beta.md
 
 
0008_protocol_dispatch_unify.md
0008_protocol_dispatch_unify.md
 
 
0009_object_header_heap_only_lock.md
0009_object_header_heap_only_lock.md
 
 
0010_stm_tier_a_mvcc.md
0010_stm_tier_a_mvcc.md
 
 
0011_host_extension_mechanism.md
0011_host_extension_mechanism.md
 
 
0012_nan_box_valuetag_day1.md
0012_nan_box_valuetag_day1.md
 
 
0013_tier_d_permanent.md
0013_tier_d_permanent.md
 
 
0014_utf8_internal_string.md
0014_utf8_internal_string.md
 
 
0015_io_interface_zone0_vtable.md
0015_io_interface_zone0_vtable.md
 
 
0016_file_size_smell_detector.md
0016_file_size_smell_detector.md
 
 
0017_allocator_strategy.md
0017_allocator_strategy.md
 
 
0018_error_catalog_ssot.md
0018_error_catalog_ssot.md
 
 
0019_crash_policy.md
0019_crash_policy.md
 
 
0020_adr_governance.md
0020_adr_governance.md
 
 
0021_test_taxonomy.md
0021_test_taxonomy.md
 
 
0022_differential_wiring.md
0022_differential_wiring.md
 
 
0023_comptime_stub_pattern.md
0023_comptime_stub_pattern.md
 
 
0024_scan_and_runner.md
0024_scan_and_runner.md
 
 
0025_chapter_archive_boundary.md
0025_chapter_archive_boundary.md
 
 
0026_phase5_entry_scope.md
0026_phase5_entry_scope.md
 
 
0027_nan_box_second_generation.md
0027_nan_box_second_generation.md
 
 
0028_mark_sweep_gc_three_layer_allocator.md
0028_mark_sweep_gc_three_layer_allocator.md
 
 
0029_runtime_java_cljw_layout.md
0029_runtime_java_cljw_layout.md
 
 
0030_defer_defrecord_reify_to_phase7.md
0030_defer_defrecord_reify_to_phase7.md
 
 
0031_regex_engine_choice.md
0031_regex_engine_choice.md
 
 
0032_bootstrap_multifile_inns.md
0032_bootstrap_multifile_inns.md
 
 
0033_clojure_ns_placement_naming_polymorphism.md
0033_clojure_ns_placement_naming_polymorphism.md
 
 
0034_cljw_build_single_mode_tier0_metadata_edn_decode.md
0034_cljw_build_single_mode_tier0_metadata_edn_decode.md
 
 
0035_require_spec.md
0035_require_spec.md
 
 
0036_dual_backend_parity_contract.md
0036_dual_backend_parity_contract.md
 
 
0037_symbol_heap_value.md
0037_symbol_heap_value.md
 
 
0038_analyzer_def_pre_register.md
0038_analyzer_def_pre_register.md
 
 
0039_reified_instance_minimal_layout.md
0039_reified_instance_minimal_layout.md
 
 
0040_vm_method_dispatch_opcodes.md
0040_vm_method_dispatch_opcodes.md
 
 
0041_multi_arity_fn_shape.md
0041_multi_arity_fn_shape.md
 
 
0042_apply_variadic_rest_bind.md
0042_apply_variadic_rest_bind.md
 
 
0043_zip_loc_record_shape.md
0043_zip_loc_record_shape.md
 
 
0044_bench_history_schema.md
0044_bench_history_schema.md
 
 
0045_phase9_scope_modules_externals.md
0045_phase9_scope_modules_externals.md
 
 
0046_upstream_skip_taxonomy.md
0046_upstream_skip_taxonomy.md
 
 
0047_vm_peephole_optimizer.md
0047_vm_peephole_optimizer.md
 
 
0048_state_machine_domains.md
0048_state_machine_domains.md
 
 
0049_orbstack_linux_gate_retired.md
0049_orbstack_linux_gate_retired.md
 
 
0050_unified_interop_call_node.md
0050_unified_interop_call_node.md
 
 
0051_interim_goal_recut_quality_loop.md
0051_interim_goal_recut_quality_loop.md
 
 
0052_universal_equality_eq_vs_numeric_equiv.md
0052_universal_equality_eq_vs_numeric_equiv.md
 
 
0053_general_compare.md
0053_general_compare.md
 
 
0054_lazy_seq_layer2.md
0054_lazy_seq_layer2.md
 
 
0055_binding_special_form_and_error_context_dynamic_var.md
0055_binding_special_form_and_error_context_dynamic_var.md
 
 
0056_aot_bootstrap.md
0056_aot_bootstrap.md
 
 
0057_sorted_collections_red_black.md
0057_sorted_collections_red_black.md
 
 
0058_eval_runtime_primitive_macro_table_reach.md
0058_eval_runtime_primitive_macro_table_reach.md
 
 
0059_class_type_return_interned_type_descriptor.md
0059_class_type_return_interned_type_descriptor.md
 
 
0060_internal_errors_catchable_via_ex_info_class_name.md
0060_internal_errors_catchable_via_ex_info_class_name.md
 
 
0061_java_static_field_resolution.md
0061_java_static_field_resolution.md
 
 
0062_context_budget_reduction.md
0062_context_budget_reduction.md
 
 
0063_compact_range_value.md
0063_compact_range_value.md
 
 
0064_transient_hash_map.md
0064_transient_hash_map.md
 
 
0065_reduce_fusion_via_transducers_chunked.md
0065_reduce_fusion_via_transducers_chunked.md
 
 
0066_deftype_macro_conversion.md
0066_deftype_macro_conversion.md
 
 
0067_eduction_as_reiterable_deftype.md
0067_eduction_as_reiterable_deftype.md
 
 
0068_sequential_marker_print_form.md
0068_sequential_marker_print_form.md
 
 
0069_contains_vector_index_semantics.md
0069_contains_vector_index_semantics.md
 
 
0070_vm_default_intent_and_parity_blockers.md
0070_vm_default_intent_and_parity_blockers.md
 
 
0071_vm_cleanup_handler_kind.md
0071_vm_cleanup_handler_kind.md
 
 
0072_protocol_extension_over_native_classes.md
0072_protocol_extension_over_native_classes.md
 
 
0073_reader_tagged_literal_infra.md
0073_reader_tagged_literal_infra.md
 
 
0074_uuid_value_type.md
0074_uuid_value_type.md
 
 
0075_tagged_literal_value.md
0075_tagged_literal_value.md
 
 
0076_clj_parity_campaign_and_accepted_divergences.md
0076_clj_parity_campaign_and_accepted_divergences.md
 
 
0077_bigdecimal_scale_independent_key.md
0077_bigdecimal_scale_independent_key.md
 
 
0078_mapentry_distinct_type.md
0078_mapentry_distinct_type.md
 
 
0079_inst_date_typed_instance.md
0079_inst_date_typed_instance.md
 
 
0080_heap_boxed_long.md
0080_heap_boxed_long.md
 
 
0081_atom_watches.md
0081_atom_watches.md
 
 
0082_syntax_quote.md
0082_syntax_quote.md
 
 
0083_namespace_as_value.md
0083_namespace_as_value.md
 
 
0084_filesystem_require.md
0084_filesystem_require.md
 
 
0085_namespace_as_runtime_value.md
0085_namespace_as_runtime_value.md
 
 
0086_macro_form_env_args.md
0086_macro_form_env_args.md
 
 
0087_persistent_queue.md
0087_persistent_queue.md
 
 
0088_print_length_level.md
0088_print_length_level.md
 
 
0089_recut_concurrency_and_drift_methods.md
0089_recut_concurrency_and_drift_methods.md
 
 
0090_phase_b_concurrency_redesign.md
0090_phase_b_concurrency_redesign.md
 
 
0091_operand_stack_root_thread_union.md
0091_operand_stack_root_thread_union.md
 
 
0092_heap_value_monitor_locking.md
0092_heap_value_monitor_locking.md
 
 
0093_agent_serial_executor.md
0093_agent_serial_executor.md
 
 
0094_primitive_reentrancy_rooting.md
0094_primitive_reentrancy_rooting.md
 
 
0095_external_container_gc_rooting.md
0095_external_container_gc_rooting.md
 
 
0096_set_bang_thread_bound_gate.md
0096_set_bang_thread_bound_gate.md
 
 
0097_with_local_vars_anon_var_lifetime.md
0097_with_local_vars_anon_var_lifetime.md
 
 
0098_cljw_http_server_surface.md
0098_cljw_http_server_surface.md
 
 
0099_wasm_ffi_minimal_surface.md
0099_wasm_ffi_minimal_surface.md
 
 

README.md

Architecture Decision Records

Load-bearing decisions only. ADRs document why a decision was made so that future readers (including future Claude sessions) do not re-litigate it. Skip ADRs for ephemeral choices ("not worth it right now") or for facts that are obvious from the code.

Filename convention

NNNN_<snake_slug>.md

  • NNNN — 4-digit sequential index, zero-padded
  • <snake_slug> — short English identifier in snake_case
  • 0000_template.md — template (do not delete or renumber)

Required structure

Use 0000_template.md as the starting point. Every ADR has:

  • Status: Proposed / Accepted / Superseded by NNNN / Deprecated
  • Context: what motivated the decision (constraints, prior art)
  • Decision: what was chosen
  • Alternatives considered: what was rejected and why
  • Consequences: positive, negative, neutral
  • References: ROADMAP §, related ADRs, external docs

Lifecycle

  • Add: when a load-bearing decision surfaces in the autonomous loop. Number = max(existing) + 1. The AI drafts the ADR with Status: Proposed → Accepted in the same cycle, lands the doc commit, and proceeds with the source change. No external review gate.
  • Supersede: do not edit a historical ADR. Add a new one and mark the old one Status: Superseded by NNNN.
  • Reject after consideration: also add an ADR with Status: Proposed → Rejected. Records why the path was not taken.

Commit gate trigger

Adding .dev/decisions/NNNN_<slug>.md (real ADRs; not README.md and not 0000_template.md) makes the commit "source-bearing" per scripts/check_learning_doc.sh. The next doc commit must include the ADR's commit SHA in its commits: front-matter list — see skill code_learning_doc.