.rules

RULESET ctxledger_repository_rules_v1.1

SECTION language
RULE default_language
SET default_language = EN

RULE user_note_language
ALLOW user_notes_language = JA

SECTION canonical_posture
RULE canonical_system_of_record
DO use ctxledger as canonical_system_of_record for:
- workflow_progress
- resumability
- projection_state
- durable_memory

RULE local_notes_are_auxiliary
DO treat repository_notes, resume_artifacts, local_continuation_files as auxiliary_or_derived
UNLESS repository_explicitly_marks_them_canonical

RULE prefer_recoverability
PREFER reliable_resumability_over_brevity
PREFER explicit_operational_trail_over_ambiguous_minimalism

SECTION workflow
RULE track_workspace
DO workspace_register_before_work_if_untracked
DO begin_or_resume_ctxledger_workflow_for_every_session
DO treat_user_request_handling_as_work_requiring_canonical_tracking

RULE resume_safely
PREFER resume_existing_workflow_before_starting_new
DO attempt_canonical_session_recovery_at_session_start_when_workspace_known
NEVER pass workspace_id_to workflow_resume
NEVER guess workflow_instance_id
IF only_workspace_id_known
THEN recover_workflow_from_canonical_context_else_start_new
IF canonical_session_recovery_fails_and_work_will_proceed
THEN start_new_canonical_workflow_instead_of_working_untracked

RULE workflow_ids
READ literally:
- workspace_register -> workspace_id
- workflow_start -> workflow_instance_id, attempt_id
- workflow_resume -> workflow_instance_id
- workflow_checkpoint -> workflow_instance_id, attempt_id
- workflow_complete -> workflow_instance_id, attempt_id

RULE checkpoint_discipline
DO workflow_checkpoint_for_meaningful_progress
DO checkpoint_session_intake_when_user_request_sets_or_changes_objective
DO checkpoint_before_final_response_when_meaningful_work_occurred_without_later_checkpoint
DO preserve continuation_critical_structure_in_checkpoints_when_known
DO preserve next_concrete_action_and_verification_context_in_planning_or_validation_checkpoints_when_known
AFTER:
- planning_or_narrowing
- root_cause_or_key_decision
- code_change_completion
- test_add_or_update
- validation_or_debug_completion
- blocker_or_handoff
- user_request_interpretation_or_scope_lock
- documentation_slice_completion

RULE checkpoint_required_structured_fields
INCLUDE in_checkpoint_when_known:
- current_objective
- next_intended_action
- verify_status
- what_remains

RULE checkpoint_preferred_structured_fields
PREFER including in_checkpoint_when_known:
- root_cause
- recovery_pattern
- verify_target
- resume_hint
- blocker_or_risk
- failure_guard
- what_changed
- what_was_learned

RULE checkpoint_prose_context
USE checkpoint_prose_for:
- rationale
- tradeoffs
- nuance
- human_readable_context
DO NOT use prose_as_only_carrier_when required_structured_fields_are_known

RULE checkpoint_next_narrow_action
FOR active_work
DO preserve one_executable_next_action_in_checkpoint_when_known
PREFER one_narrow_slice_over_broad_future_intent

RULE checkpoint_verify_target
WHEN verification_target_is_known
DO record verify_target_explicitly
PREFER named_test_or_suite_or_command_or_validation_surface_over_generic_claims

RULE completion_guard
NEVER complete_workflow_when:
- task_is_diagnostic
- task_is_exploratory
- root_cause_not_yet_confident
- multiple_plausible_hypotheses_remain
- meaningful_next_investigation_exists
- user_has_not_signaled_stop

RULE completion_discipline
DO treat workflow_complete_as_terminal
NEVER use workflow_complete_as_save_progress
NEVER checkpoint_after_terminal_workflow
IF more_work_remains
THEN checkpoint_instead_of_complete

RULE workflow_failure_visibility
WHEN workflow_ops_fail
DO diagnose_before_retry
NEVER silently_ignore_failure
IF failure_persists
THEN continue_only_with_explicit_degraded_state_awareness

RULE end_of_loop
WHEN work_loop_is_done
DO:
- workflow_complete
- commit_descriptive_git_changes_if_any
- leave_resumption_context_for_next_session
- ensure_user_visible_outcome_is_reflected_in_canonical_workflow_state

SECTION memory
RULE use_memory_tools_when_material
USE memory_tools_only_when_they_improve_recall_continuity_or_decision_quality

RULE memory_get_context_reading
TREAT memory_get_context_as hierarchy_aware_not_flat
READ structured_fields_first:
- summary_selection_applied
- summary_selection_kind
- memory_context_groups
- retrieval_routes_present
- primary_retrieval_routes_present
- auxiliary_retrieval_routes_present
- retrieval_route_presence
- retrieval_route_group_counts
- retrieval_route_item_counts
- summary_first_has_episode_groups
- summary_first_is_summary_only
- summary_first_child_episode_count
- summary_first_child_episode_ids
- primary_episode_groups_present_after_query_filter
- auxiliary_only_after_query_filter

RULE route_meanings
INTERPRET:
- summary_first = primary_summary_selected_path
- episode_direct = direct_visible_episode_path
- workspace_inherited_auxiliary = inherited_workspace_auxiliary_context
- relation_supports_auxiliary = relation_derived_auxiliary_context
- graph_summary_auxiliary = derived_graph_backed_auxiliary_context

RULE summary_truth_boundary
READ summary_state_as canonical_relational_first
READ graph_summary_auxiliary_as derived_and_degradable
NEVER treat graph_summary_auxiliary_as_canonical_truth

RULE summary_modes
IF summary_first_has_episode_groups = true
THEN interpret_as summary_plus_episode_primary_output
IF summary_first_is_summary_only = true
THEN interpret_as summary_only_primary_output
NEVER collapse_summary_only_primary_into_auxiliary_only

RULE episode_less_path
IF include_episodes = false
THEN read_only_surfaced_fields_and_routes
AND do_not_assume_hidden_summary_first_placeholders

RULE summary_selection_kind
INTERPRET:
- memory_summary_first = canonical_summary_first_selection
- episode_summary_first = episode_derived_summary_fallback

RULE route_metadata_when_origin_matters
WHEN context_origin_matters
USE route_metadata_explicitly
NEVER infer_origin_only_from_text_presence

RULE memory_search_usage
USE memory_search_for:
- similar_prior_work
- prior_failures_or_tradeoffs
- reusable_patterns_or_recovery
- interaction_or_file_work_signals_when_debugging_or_repeating_work
- file_work_linked_context_restoration_when_resuming_or_continuing_work

RULE interaction_promotion_usage
USE interaction_memory_for:
- bounded_recall
- resumability_support
- historical_progress_lookup
- file_work_intent_recall
PROMOTE only_high_signal_interaction_material_for:
- root_cause_clarification
- retry_decision
- resume_decision
- fallback_prevention_decision
- user_correction_that_changes_execution_direction
- orchestration_boundary_finding
- file_work_intent_that_materially_affects_recovery

RULE remember_episode_usage
USE memory_remember_episode_for_high_signal_knowledge:
- non_obvious_root_cause
- important_decision
- reusable_debugging_pattern
- failure_and_recovery
- process_lesson

RULE completion_auto_memory_default
DO treat workflow_completion_auto_memory_as_default_closeout_path
FOR:
- normal_workflow_completion
- normal_failure_closeout
- normal_cancellation_closeout
WHEN completion_fields_are_available
READ as gated_not_guaranteed

RULE explicit_episode_vs_auto_memory
USE memory_remember_episode_in_addition_to_workflow_completion_auto_memory
ONLY_FOR high_signal_knowledge_not_safely_captured_by_closeout_automation
SUCH_AS:
- non_obvious_root_cause
- important_decision
- reusable_debugging_pattern
- failure_and_recovery_lesson
- process_lesson_with_reuse_value

RULE avoid_duplicate_closeout_episodes
DO NOT use memory_remember_episode_only_to_repeat_workflow_complete_summary
OR restate_checkpoint_fields_already_recorded_for_closeout
WHEN no_additional_high_signal_memory_is_added

RULE completion_structured_fields
DO include_structured_checkpoint_fields_when_known:
- current_objective
- next_intended_action
- root_cause
- recovery_pattern
- what_remains
- verify_status
- verify_target
- resume_hint
- blocker_or_risk
- failure_guard

RULE prefer_high_signal_episodes
PREFER fewer_higher_signal_memory_episodes_over_repetition

RULE summary_build_requesting
WHEN explicit_closeout_summary_is_needed
DO set latest_checkpoint.checkpoint_json.build_episode_summary = true
BEFORE workflow_complete
DO request_summary_build_more_often_for:
- high_signal_workflow_completion_with_passed_verification
- repeated_checkpoint_theme_with_clear_reuse_value
- high_signal_failure_and_recovery_lesson
- closeout_with_reusable_process_lesson

RULE summary_build_high_signal_triggering
PREFER requesting_summary_build_for:
- high_signal_closeout_with_passed_verification
- repeated_theme_closeout_with_reuse_value
- high_signal_failure_and_recovery
- reusable_process_lesson
DO NOT request_summary_build_only_because workflow_is_terminal

RULE closeout_memory_fallback
IF workflow_completion_auto_memory_is_skipped_or_insufficient
THEN use memory_remember_episode_only_for_new_high_signal_knowledge

RULE observability_baseline_checks
AFTER deployment_or_runtime_behavior_change
CHECK when_relevant:
- stats
- memory-stats
- age-graph-readiness

RULE observability_agent_quality_checks
CHECK when_relevant:
- structured_checkpoint_coverage
- summary_build_request_rate
- summary_build_success_visibility
- summary_build_skip_visibility
- aggregate_resume_success_visibility
- aggregate_resume_failure_visibility
- fallback_prevention_visibility

RULE observability_hygiene_checks
CHECK when_relevant:
- summary_backlog
- unlinked_interaction_volume
- weak_linkage_visibility
- null_workspace_memory_volume
- missing_expected_file_work_coverage_when_detectable

RULE observability_signal_reading
READ as operator_signals_not_canonical_truth:
- interaction_memory_item_count
- file_work_memory_item_count
- structured_checkpoint_coverage
- summary_backlog
- unlinked_interaction_volume
- null_workspace_memory_volume

RULE file_work_recording_required
DO record file-touching work in ctxledger when the agent:
- creates_a_file
- modifies_a_file
- overwrites_a_file
- copies_a_file
- moves_or_renames_a_file
- deletes_a_file
- restores_a_file
- saves_a_file_after_meaningful_work
INCLUDE when known:
- workflow_instance_id
- attempt_id
- file_path
- file_name
- file_operation
- purpose
- work_loop_context

RULE file_work_recording_scope
DO link file-work records to the active work loop
DO preserve repository_relative_or_canonical_file_path_when_possible
DO preserve why_the_file_was_touched_not_only_that_it_was_touched
NEVER record file-work as detached_unscoped_notes_when workflow_context_is_available

RULE file_work_recovery_usage
DO use recorded file-work memory as context-restoration material for:
- resume
- continue
- work_loop_recovery
- historical_file_work_lookup
DO prefer file-work-linked durable memory over ad_hoc recollection when reconstructing agent work context

RULE file_work_required_for_context_restoration
READ file-work memory as required_context_material_for_ai_agent_work_restoration
WHEN file_touching_work_occurred
DO treat missing_file_work_recording_as a resumability_gap_not_a_minor_observability_gap

RULE memory_episode_content
WHEN recording_episode
INCLUDE:
- what_happened
- why_it_mattered
- how_to_apply_later

SECTION change_sizing
RULE keep_changes_small
PREFER one_clear_behavior_change_or_one_narrow_refactor_or_one_focused_doc_update_per_slice
IF task_is_large
THEN split_into_small_semantic_slices
NEVER mix_unrelated_concerns_without_need

RULE test_and_doc_focus
PREFER focused_test_scenarios_with_single_assertion_theme
PREFER short_topic_focused_doc_sections

SECTION agent_behavior
RULE prefer_explicit_state_transitions
PREFER explicit_state_transitions_over_implicit_assumptions

RULE session_tracking_visibility
NEVER treat_rules_file_detection_as_equivalent_to_canonical_tracking
DO ensure_every_session_has_explicit_ctxledger_state_transition_when_work_is_performed
DO reflect_session_start_progress_and_session_end_progress_in_canonical_workflow_records
DO treat_investigation_documentation_planning_and_explanation_work_as_trackable_work_not_exceptions

RULE prefer_structure_over_prose
WHEN structured_tool_fields_and_prose_both_exist
PREFER structured_fields
NEVER omit required_structured_checkpoint_fields_only_because prose_summary_exists

RULE parallelize_independent_operations
PREFER parallel_execution_over_serial_execution
WHEN multiple_operations_are_independent
AND all_required_parameters_are_known
AND no_operation_depends_on_another_operation_result

RULE dependency_ordering
DO execute_sequentially
WHEN an_operation_requires_a_previous_result
OR parallel_execution_would_violate_tool_constraints_or_change_intended_behavior

RULE workflow_completion_payloads
IF auto_memory_details_present
THEN inspect_before_summarizing

RULE summary_build_payload
IF auto_memory_details.summary_build_present
THEN treat_as_authoritative_for:
- summary_build_attempted
- summary_build_succeeded
- summary_build_requested
- summary_build_status
- summary_build_skipped_reason
- summary_build_trigger
- summary_build_scope
- summary_build_replace_existing
- summary_build_replaced_existing_summary
- built_memory_summary_id
- built_summary_membership_count

RULE do_not_flatten_summary_build
NEVER compress_structured_summary_build_outcomes_into_vague_claims

RULE summary_automation_policy
READ literally:
- default_requested = false
- request_field = latest_checkpoint.checkpoint_json.build_episode_summary
- trigger = latest_checkpoint.build_episode_summary_true
TREAT workflow_summary_automation_as:
- explicit
- checkpoint_gated
- non_fatal

RULE keep_facts_separate
KEEP_SEPARATE:
- auto_memory_recorded
- summary_build_attempted
- summary_build_succeeded

SECTION response_style

RULE terse_default
PREFER shortest_complete_answer
PREFER direct_answer_first
EXPAND only_when_user_explicitly_requests_detail

RULE japanese_conciseness
PREFER plain_japanese_over_polite_japanese
AVOID honorific_padding
AVOID ceremonial_openings_and_closings
AVOID verbose_transitions

RULE no_redundancy
NEVER restate_user_request
NEVER repeat_same_point_in_different_words
NEVER add_summary_if_answer_already_starts_with_conclusion

RULE structure_for_brevity
PREFER short_sentences
PREFER bullets_for_distinct_items_only
LIMIT alternatives_to_two_when_materially_needed
LIMIT examples_to_one_unless_requested

RULE output_budget
WHEN user_does_not_request_detail
PREFER response_within:
- 3_to_8_lines
- 1_to_5_bullets
- 1_to_3_short_paragraphs

RULE uncertainty_policy
STATE uncertainty_only_when_real
AVOID habitual_hedging

RULE actionability
PREFER concrete_recommendation_over_broad_option_listing
WHEN one_best_default_exists
GIVE that_first