Polishing refactored Donna#84
Merged
Merged
Conversation
Acked-by: Aliaksei Yaletski (Tiendil) <a.eletsky@gmail.com>
There was a problem hiding this comment.
Pull request overview
This PR polishes the refactored Donna codebase by tightening workspace/config discovery, reworking protocol/journal output plumbing, formalizing specifications/docs, and updating the build/dev toolchain (uv/hatch + tach).
Changes:
- Replace the “artifacts” skill/docs framing with “workflows”, add/organize new
specs/documents, and update RFC/workflow docs accordingly. - Refactor runtime/session + protocol output paths (cells/journal/errors) and align template/directive contexts around machine-owned render modes.
- Switch packaging/development workflow from Poetry to Hatch/uv, add Tach dependency-layer config, and extend CI to run tests.
Reviewed changes
Copilot reviewed 190 out of 210 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| workflows/rfc/specs/request_for_change.md | Update RFC instructions to reference donna skill workflows. |
| workflows/rfc/specs/design.md | Update RFC instructions to reference donna skill workflows. |
| workflows/rfc/request.donna.md | Update workflow to reference donna skill workflows. |
| workflows/rfc/plan.donna.md | Update workflow to reference donna skill workflows. |
| workflows/rfc/design.donna.md | Update workflow to reference donna skill workflows. |
| workflows/examples/time_to_drink_tea.donna.md | Add example workflow demonstrating branching and task variables. |
| tach.toml | Add Tach module/layer configuration and external exclusions. |
| specs/meta/general.md | Add general requirements for specification documents. |
| specs/intro.md | Replace intro prose with a specification index. |
| specs/documentation/readme.md | Add spec describing README.md requirements. |
| specs/documentation/changelog.md | Add spec describing changelog tooling/format (Changy). |
| specs/dictionary.md | Add shared terminology for project specifications. |
| specs/core/top_level_architecture.md | Remove old top-level architecture doc (replaced by new specs structure). |
| specs/architecture/naming.md | Add architecture-level naming conventions spec. |
| pyproject.toml | Switch build backend to hatchling, move dev deps to dependency-groups, tighten mypy, add hatch build includes, add pytest deps. |
| donna/workspaces/utils.py | Add project-dir discovery helpers under workspaces. |
| donna/workspaces/tests/test_utils.py | Add tests for workspace discovery helpers. |
| donna/workspaces/tests/test_symbol_coverage.py | Add meta-test enforcing per-symbol test class coverage for workspaces. |
| donna/workspaces/tests/test_sessions.py | Add tests for workspace session directory/state helpers. |
| donna/workspaces/tests/test_files.py | Add tests for file fingerprint helper. |
| donna/workspaces/tests/make.py | Add test builders for workspaces parsing/sections. |
| donna/workspaces/templates.py | Move render mode ownership to machine layer; tighten directive context typing/casts. |
| donna/workspaces/markdown.py | Narrow config typing and adjust markdown parsing safety around root node. |
| donna/workspaces/markdown_parser.py | Update parsing to pydantic v2 model_validate, machine-owned RenderMode, and primitive-id parsing helper. |
| donna/workspaces/journal.py | Update type import to protocol JournalRecord. |
| donna/workspaces/initialization.py | Rework workspace loading/initialization around explicit config path discovery + new errors. |
| donna/workspaces/fixtures/base_config.toml | Update base config fixture to include version and new [defaults] shape. |
| donna/workspaces/errors.py | Add workspace config discovery/not-found/dir-not-found errors. |
| donna/workspaces/config.py | Add version, [defaults] config section, store config_path in Workspace, and add global config_path. |
| donna/workspaces/artifacts.py | Use new defaults config nesting and machine-owned RenderMode. |
| donna/workspaces/init.py | Export workspaces package submodules. |
| donna/skills/tests/test_fixtures.py | Add fixture/resource tests for skill docs. |
| donna/skills/tests/test_entities.py | Add tests for SkillDocument enum values. |
| donna/skills/fixtures/artifacts.md | Remove obsolete “artifacts” skill fixture. |
| donna/skills/fixtures.py | Point fixtures map from artifacts to workflows. |
| donna/skills/entities.py | Rename skill document enum member to workflows. |
| donna/skills/init.py | Export entities/fixtures modules alongside public API. |
| donna/runtime/tests/make.py | Add runtime test helpers for context/artifacts/state/primitives. |
| donna/runtime/tests/init.py | Add runtime tests package marker. |
| donna/runtime/sessions.py | Adjust session load/new-session behavior and journal wiring via runtime context. |
| donna/runtime/init.py | Export runtime module entry points. |
| donna/protocol/utils.py | Remove old instant output helpers (replaced by emitters). |
| donna/protocol/tests/test_nodes.py | Add tests for node status/info/references composition defaults. |
| donna/protocol/tests/test_modes.py | Add tests for mode-to-formatter selection and unsupported mode error. |
| donna/protocol/tests/test_journal.py | Add tests for protocol journal serialization and newline validation. |
| donna/protocol/tests/test_errors.py | Add tests for environment error node rendering/metadata. |
| donna/protocol/tests/test_cells.py | Add tests for cell building, metadata conversion, and short id. |
| donna/protocol/tests/test_cell_shortcuts.py | Add tests for common cell shortcut helpers. |
| donna/protocol/tests/make.py | Add protocol test factories for cells/journal records. |
| donna/protocol/modes.py | Change formatter selection to accept explicit Mode argument. |
| donna/protocol/journal.py | Introduce protocol-owned JournalRecord model and JSON serialization. |
| donna/protocol/formatters/tests/test_llm.py | Add tests for LLM formatter output format. |
| donna/protocol/formatters/tests/test_human.py | Add tests for human formatter output format. |
| donna/protocol/formatters/tests/test_automation.py | Add tests for automation formatter JSONL output. |
| donna/protocol/formatters/llm.py | Switch formatter to protocol JournalRecord. |
| donna/protocol/formatters/human.py | Switch formatter to protocol JournalRecord. |
| donna/protocol/formatters/base.py | Switch formatter base to protocol JournalRecord. |
| donna/protocol/formatters/automation.py | Emit JSONL lines for cells and journal records; add helper for JSON line formatting. |
| donna/protocol/formatters/init.py | Export protocol formatter base type. |
| donna/protocol/errors.py | Add protocol error node wrapper for environment errors. |
| donna/protocol/cells.py | Expand MetaValue support and conversion rules. |
| donna/protocol/init.py | Export protocol submodules. |
| donna/primitives/tests/make.py | Add primitive test helpers (template context, fake runtime context). |
| donna/primitives/tests/init.py | Add primitives tests package marker. |
| donna/primitives/sections/tests/test_request_action.py | Add tests for request_action transitions/meta and execution. |
| donna/primitives/sections/tests/test_output.py | Add tests for output meta/validation/execute behavior. |
| donna/primitives/sections/tests/test_finish_workflow.py | Add tests for finish operation meta/execute behavior. |
| donna/primitives/sections/tests/init.py | Add sections tests package marker. |
| donna/primitives/sections/run_script.py | Switch journaling to runtime context journal. |
| donna/primitives/sections/output.py | Switch output emission from protocol utils to context output emitter. |
| donna/primitives/sections/finish_workflow.py | Switch output emission from protocol utils to context output emitter. |
| donna/primitives/sections/init.py | Export section primitives. |
| donna/primitives/directives/tests/test_task_variable.py | Add tests for TaskVariable directive behavior. |
| donna/primitives/directives/tests/test_goto.py | Add tests for GoTo directive behavior and formatting. |
| donna/primitives/directives/tests/init.py | Add directives tests package marker. |
| donna/primitives/directives/task_variable.py | Update directive signatures/context typing and adjust argument handling. |
| donna/primitives/directives/goto.py | Update directive signatures/context typing and switch --config in rendered command. |
| donna/primitives/directives/init.py | Export directive primitives. |
| donna/primitives/artifacts/workflow.py | Tighten meta typing for cells metadata and add mapping imports. |
| donna/primitives/artifacts/tests/init.py | Add artifacts tests package marker. |
| donna/primitives/artifacts/init.py | Export artifact primitives. |
| donna/primitives/init.py | Export primitives subpackages. |
| donna/machine/tests/test_templates.py | Add tests for directive rendering modes and preparation errors. |
| donna/machine/tests/test_tasks.py | Add tests for task/work unit build/run behavior and context scope restoration. |
| donna/machine/tests/test_primitives.py | Add tests for primitive defaults and primitive resolution error cases. |
| donna/machine/tests/test_operations.py | Add tests for operation meta cell serialization. |
| donna/machine/tests/test_errors.py | Add tests for artifact validation error intros. |
| donna/machine/tests/test_context.py | Add tests for machine context var and ValueScope. |
| donna/machine/tests/test_changes.py | Add tests for change application behavior to mutable state. |
| donna/machine/tests/test_action_requests.py | Add tests for action request build/node output. |
| donna/machine/tests/make.py | Add machine test factories for artifacts/state/ids. |
| donna/machine/tests/helpers.py | Add fake machine context/artifacts/primitives/journal helpers for tests. |
| donna/machine/templates.py | Move RenderMode into machine, tighten directive typing, and align directive apply behavior. |
| donna/machine/templates_context.py | Add DirectiveContext type alias for directive rendering contexts. |
| donna/machine/tasks.py | Tighten context typing, switch artifact load to execution-specific loader, and journal via machine context. |
| donna/machine/state.py | Route artifact loads via context caches and journal through context journal; align view/execution loads. |
| donna/machine/primitives.py | Tighten directive typing and restrict primitive resolution to PythonPath. |
| donna/machine/operations.py | Tighten cells metadata typing for operation meta. |
| donna/machine/journal.py | Remove machine-owned journal implementation (moved to protocol/context). |
| donna/machine/errors.py | Add MachineContextNotSet and update some user guidance strings. |
| donna/machine/context.py | Introduce machine context var and shared ValueScope + context protocols. |
| donna/machine/artifacts.py | Tighten meta typing and route environment errors via protocol environment error nodes. |
| donna/machine/init.py | Export machine submodules. |
| donna/lib/tests/test_init.py | Add tests ensuring donna.lib exports initialized primitive instances. |
| donna/lib/tests/init.py | Add lib tests package marker. |
| donna/lib/init.py | Switch imports to use new primitives package exports. |
| donna/domain/tests/test_internal_ids.py | Add tests for internal id build/validate/pydantic integration. |
| donna/domain/tests/test_ids.py | Add tests for identifier/section id behavior and pydantic validation. |
| donna/domain/tests/test_id_paths.py | Add tests for id path parsing/ordering/immutability and python path validation. |
| donna/domain/tests/test_artifact_ids.py | Add tests for artifact id/section id validation and splitting. |
| donna/domain/paths.py | Expand PathInput union to include config path/pathlib path. |
| donna/domain/internal_ids.py | Tighten typing for validators and schema hooks. |
| donna/domain/ids.py | Tighten typing for validators and schema hooks. |
| donna/domain/id_paths.py | Tighten typing for validators and schema hooks; improve schema builder typing. |
| donna/domain/artifact_ids.py | Tighten typing for validators/splitting inputs. |
| donna/domain/init.py | Export domain submodules. |
| donna/core/utils.py | Reduce core utils to now() only (workspace discovery moved). |
| donna/core/tests/test_utils.py | Add tests for now() semantics. |
| donna/core/tests/test_result.py | Add tests for Result behavior, mapping, and unwrap wrapper. |
| donna/core/tests/test_errors.py | Add tests for internal/environment error behaviors and proxy exception. |
| donna/core/tests/test_entities.py | Add tests for base entity config (strip strings, frozen, replace, JSON roundtrip). |
| donna/core/result.py | Tighten typing/covariance for Result, Ok, and Err. |
| donna/core/errors.py | Remove embedded environment error node + old project dir error and tighten typing. |
| donna/core/entities.py | Tighten typing on entity replace(). |
| donna/core/init.py | Export core submodules. |
| donna/context/value_scope.py | Remove old value scope implementation (moved to machine). |
| donna/context/tests/test_state.py | Add tests for state cache load/save/fingerprint behavior. |
| donna/context/tests/test_primitives.py | Add tests for primitives cache resolution and caching behavior. |
| donna/context/tests/test_journal.py | Add tests for context journal actor id selection and record emission. |
| donna/context/tests/test_context.py | Add tests for runtime context init and context var set/reset. |
| donna/context/tests/make.py | Add context test helper for fake raw artifact. |
| donna/context/tests/helpers.py | Add fake emitters/journal for tests. |
| donna/context/tests/init.py | Add context tests package marker. |
| donna/context/output.py | Add output emitter protocol + noop emitter. |
| donna/context/journal.py | Add runtime journal implementation that writes + emits journal records. |
| donna/context/context.py | Add runtime context output/journal and reuse machine ValueScope. |
| donna/context/artifacts.py | Add view/execution artifact loaders that construct appropriate render context. |
| donna/context/init.py | Export Journal along with runtime context helpers. |
| donna/cli/utils.py | Add CLI output emitter, route error rendering through protocol nodes, and install both runtime + machine contexts. |
| donna/cli/types.py | Rename root option to config option; update error cell rendering via protocol nodes. |
| donna/cli/tests/test_workspaces.py | Add CLI tests for init behavior (default and --config). |
| donna/cli/tests/test_version.py | Add CLI test for version output. |
| donna/cli/tests/test_skills.py | Add CLI tests for skill command behavior and invalid args. |
| donna/cli/tests/test_sessions.py | Add CLI tests for new-session and status. |
| donna/cli/tests/test_artifacts.py | Add CLI tests for list/render/validate and argument validation. |
| donna/cli/tests/helpers.py | Add CLI test runner helpers and fixture writers. |
| donna/cli/tests/conftest.py | Add fixture to isolate workspace global config between tests. |
| donna/cli/entities.py | Change global options from root_dir to config_path. |
| donna/cli/commands/workspaces.py | Update init command to initialize workspace at a config file path. |
| donna/cli/commands/sessions.py | Rename session creation command to new-session and route through runtime sessions. |
| donna/cli/commands/artifacts.py | Route journaling via context journal and environment errors via protocol nodes. |
| donna/cli/application.py | Replace --root/-r with --config in CLI callback and global options. |
| donna/cli/init.py | Export CLI submodules. |
| donna.toml | Update repo config to include version and new [defaults] block. |
| docker/Dockerfile | Switch container bootstrap to uv-based environment setup and uv sync. |
| bin/tach-map-query.py | Add helper script to query tach dependency map for an artifact. |
| bin/release-prepare.sh | Switch release script from poetry to uv/hatch commands. |
| bin/journal-tail.py | Add non-follow mode with --follow option and update CLI help. |
| bin/donna.sh | Switch dev wrapper from poetry to uv. |
| bin/dev.sh | Quote args when invoking docker compose run. |
| bin/dev-tests.sh | Add docker-backed test runner script. |
| bin/dev-check-semantics.sh | Add tach check and switch tool invocations to uv. |
| bin/dev-check-runtime.sh | Switch runtime check to uv. |
| bin/dev-check-formatting.sh | Switch formatting checks to uv. |
| AGENTS.md | Rewrite agent instructions, including docker-only dev commands and updated tooling guidance. |
| .github/workflows/code-checks.yaml | Make checkout ref fallback to github.ref and add test run step. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
89
to
+93
| if not config_blocks: | ||
| return Ok({}) | ||
|
|
||
| return config_blocks[0].structured_data() | ||
| data = config_blocks[0].structured_data().unwrap() | ||
| return Ok(cast(dict[str, object], data)) |
Comment on lines
45
to
+49
| def output_cells(cells: Iterable[Cell]) -> None: | ||
| formatter = get_cell_formatter() | ||
| emitter = CliEmitter(get_cell_formatter(workspace_config.protocol())) | ||
|
|
||
| for cell in cells: | ||
| output = formatter.format_cell(cell) | ||
| sys.stdout.buffer.write(output) | ||
| emitter.emit_cell(cell) |
Comment on lines
28
to
33
| @@ -27,5 +29,5 @@ class OperationMeta(ArtifactSectionMeta): | |||
| fsm_mode: FsmMode = FsmMode.normal | |||
| allowed_transtions: set[SectionId] | |||
|
|
|||
| def cells_meta(self) -> dict[str, Any]: | |||
| def cells_meta(self) -> Mapping[str, MetaValue]: | |||
| return {"fsm_mode": self.fsm_mode.value, "allowed_transtions": [str(t) for t in self.allowed_transtions]} | |||
Comment on lines
+41
to
46
| def render_view(self, context: DirectiveContext, *argv: object) -> Result[object, ErrorsList]: | ||
| variable_name = str(argv[0]) | ||
| return Ok( | ||
| "$$donna at the time of execution of this section here will placed a value " | ||
| f"of the task variable '{variable_name}' donna$$" | ||
| ) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.