version: 1
generated_by: maintain-architecture-decisions
decisions:
- id: harness.agent-boundary-and-protocol
status: accepted
scope: harness
decision_type: boundary
summary: Lucy is a local macOS/Linux harness whose compiled boot guidance drives
task-specific capability discovery while cmd remains its only model-facing tool.
applies_to:
- Cargo.toml
- src/**
- tests/**
- README.md
file: records/harness/agent-boundary-and-protocol.md
constrains: []
depends_on: []
supersedes: []
superseded_by: []
last_reviewed: '2026-07-26'
enforcement:
- id: cmd-only-tool-schema
path: src/provider.rs
must_contain:
- fn normal_requests_expose_only_cmd()
- '"name": "cmd"'
must_not_contain: []
- id: normalized-jsonl-tool-loop
path: tests/cli.rs
must_contain:
- fn streams_normalized_events_runs_cmd_loop_and_keeps_stdout_pure()
must_not_contain: []
- id: codex-cmd-tool-schema
path: src/codex_provider.rs
must_contain:
- fn codex_request_uses_responses_shape()
- '"background":{"type":"boolean","default":false}'
must_not_contain: []
- id: built-in-capability-discovery-guidance
path: src/context.rs
must_contain:
- 'const BUILT_IN_SYSTEM_PROMPT: &str ='
- fn built_in_prompt_directs_task_driven_capability_discovery()
must_not_contain: []
enforcement_exception: null
- id: harness.command-execution
status: accepted
scope: harness
decision_type: execution
summary: Lucy executes trusted shell commands locally with bounded time and output,
including process-scoped background execution.
applies_to:
- src/**
- tests/**
- README.md
file: records/harness/command-execution.md
constrains: []
depends_on:
- harness.agent-boundary-and-protocol
- harness.session-and-context-lifecycle
supersedes: []
superseded_by: []
last_reviewed: '2026-07-22'
enforcement:
- id: background-command-contract
path: tests/cli.rs
must_contain:
- fn background_cmd_completion_starts_an_automatic_turn_after_turn_end()
- fn background_cmd_completion_is_delivered_before_the_active_turn_ends()
must_not_contain: []
- id: background-completion-privilege
path: src/app.rs
must_contain:
- ChatMessage::observation(content)
- fn background_completion_delimiter_cannot_be_forged_by_command_output()
must_not_contain:
- ChatMessage::system(content)
- id: observation-message-privilege
path: src/model.rs
must_contain:
- 'pub const OBSERVATION_ROLE: &str = "observation";'
- fn observation_keeps_its_session_role_but_uses_the_openai_user_role()
must_not_contain: []
- id: codex-observation-privilege
path: src/codex_provider.rs
must_contain:
- fn codex_request_maps_observations_to_unprivileged_user_input()
must_not_contain: []
- id: bounded-command-execution
path: src/command.rs
must_contain:
- 'pub const COMMAND_TIMEOUT: Duration = Duration::from_secs(10 * 60);'
- 'pub const COMMAND_OUTPUT_CAP: usize = 64 * 1024;'
must_not_contain: []
enforcement_exception: null
- id: harness.configuration-and-provider
status: accepted
scope: harness
decision_type: configuration
summary: Lucy owns a compiled built-in boot prompt, bootstraps provider settings
in an XDG config file, preserves valid legacy system_prompt keys while ignoring
them, and reads provider credentials only from the environment.
applies_to:
- src/**
- tests/**
- README.md
file: records/harness/configuration-and-provider.md
constrains: []
depends_on:
- harness.agent-boundary-and-protocol
supersedes: []
superseded_by: []
last_reviewed: '2026-07-26'
enforcement:
- id: config-bootstrap-and-migration
path: src/config.rs
must_contain:
- fn bootstraps_config_without_overwriting_existing_bytes()
- fn migrates_a_legacy_config_once_without_overwriting_xdg_config()
- fn generated_config_omits_system_prompt()
- fn legacy_system_prompt_is_ignored_without_rewriting_config_bytes()
- fn settings_updates_preserve_legacy_system_prompt()
- '#[serde(skip)]'
- fn auth_provider_rejects_mixed_credentials()
must_not_contain: []
- id: openrouter-session-identity-and-attribution
path: src/provider.rs
must_contain:
- fn openrouter_requests_include_session_and_app_metadata()
- fn compatible_requests_omit_provider_specific_session_metadata()
- 'const APP_URL: &str = "https://lucyna.run";'
must_not_contain: []
- id: codex-session-identity
path: src/codex_provider.rs
must_contain:
- fn codex_request_uses_responses_shape()
- request["prompt_cache_key"] = json!(session_id);
must_not_contain: []
enforcement_exception: null
- id: harness.session-and-context-lifecycle
status: accepted
scope: harness
decision_type: lifecycle
summary: Lucy persists named JSONL sessions, interruption records, compaction
boundaries, and the built-in composed boot prompt snapshot that was current
when each session was created.
applies_to:
- src/**
- tests/**
- README.md
file: records/harness/session-and-context-lifecycle.md
constrains: []
depends_on:
- harness.agent-boundary-and-protocol
- harness.configuration-and-provider
supersedes: []
superseded_by: []
last_reviewed: '2026-07-26'
enforcement:
- id: session-resume-and-context
path: src/session.rs
must_contain:
- fn creates_appends_resumes_and_lists_jsonl_session()
- fn resume_retains_historical_boot_system_prompt()
- fn compaction_appends_a_boundary_and_reconstructs_only_retained_messages()
- fn interruption_records_are_valid_and_resume_in_file_order_without_provider_fragments()
must_not_contain: []
enforcement_exception: null