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 with a default TUI, an automatic/explicit
JSONL session protocol, OpenAI-compatible and Codex subscription providers,
and the model-facing cmd 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-19'
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: []
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: 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 bootstraps a user-editable XDG config file, migrates the legacy
~/.lucy/config.toml once when needed, 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-25'
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 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 an immutable boot-context snapshot on resume.
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-19'
enforcement:
- id: session-resume-and-context
path: src/session.rs
must_contain:
- fn creates_appends_resumes_and_lists_jsonl_session()
- 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