gh-35 — Implemented donna journal CLI subcommands for writing and viewing session journal + gh-41 — Added Design step into RFC workflow

.donna/project/work/polish.md

@@ -5,7 +5,7 @@ kind = "donna.lib.workflow"
 start_operation_id = "run_autoflake_script"
 ```
 
-Initiate operations to polish and refine the donna codebase: running & fixing tests, formatting code, fixing type annotations, etc.
+Initiate operations to polish and refine the donna codebase: running & fixing tests, formatting code, fixing type annotations, etc. This workflow MUST NOT be used to introduce new logic into the project or refactor it — only to fix existing issues.
 
 ## Run Autoflake
 

README.md

@@ -4,6 +4,8 @@ Your agent will generate [state machines](https://en.wikipedia.org/wiki/Finite-s
 
 Donna allows your agent to execute hundreds of consecutive steps without swaying away from the defined workflow. Branching, loops, nested calls, and recursion — all possible.
 
+![Journal log demonstration](./docs/images/journal-demo.gif)
+
 ## What is Donna?
 
 Donna is a CLI tool that helps coding agents like Codex focus on the task at hand by keeping high-level control flow in explicit Donna workflows. Donna dictates what should be done at each step of the work, so the agent can focus on the actual piece.
@@ -155,11 +157,18 @@ Donna will:
 
 **Donna is a CLI tool for agents.** You rarely need to use it directly.
 
+However, it is convenient to run `donna journal view --follow` in a separate terminal to see what is going on in the current session.
+
 Commands you may need:
 
-- `donna -p human workspaces init` — Initialize Donna in your project.
-- `donna -p human sessions start` — start a new working session, remove everything from the previous session.
-- `donna -p human artifacts list <pattern>` — list artifacts with short descriptions.
+- `donna workspaces init` — Initialize Donna in your project.
+- `donna sessions start` — start a new working session, remove everything from the previous session.
+- `donna artifacts list <pattern>` — list artifacts with short descriptions.
+- `donna journal view [--lines N] [--follow]` — view the log of work performed in the current session.
+
+Here is an example of the real Donna session work log:
+
+![Journal log demonstration](./docs/images/journal-demo.gif)
 
 Use `donna --help` for a quick reference.
 
@@ -194,7 +203,7 @@ Note that the default Donna workflows are designed to be reliable and useful for
 Points of interest:
 
 - [donna:rfc:specs:request_for_change](./donna/artifacts/rfc/specs/request_for_change.md) — specification of the RFC document.
-- [donna:rfc:work:create](./donna/artifacts/rfc/work/create.md) — workflow to create a RFC document.
+- [donna:rfc:work:request](./donna/artifacts/rfc/work/request.md) — workflow to create a RFC document.
 - [donna:rfc:work:plan](./donna/artifacts/rfc/work/plan.md) — workflow to plan work on an RFC — creates a new workflow.
 - [donna:rfc:work:do](./donna/artifacts/rfc/work/do.md) — meta workflow to automate the whole work from a developer request to a changelog update.
 

changes/next_release.md

@@ -0,0 +1,13 @@
+
+### Changes
+
+- gh-35 — Implemented `donna journal` CLI subcommands for writing and viewing session journal.
+  - Added journaling of all significant actions and events.
+  - Removed `single_mode` formatting option from protocol formatter APIs.
+  - Command `donna artifacts validate` now accepts an artifact pattern instead of a single artifact id.
+  - Removed `donna artifacts validate-all` command.
+- gh-41 — Added `Design` step into RFC workflow.
+  - Added `donna:rfc:specs:design` and `donna:rfs:work:design`.
+  - Updated `donna:rfc:work:do` to include `design` step between `create` and `plan`.
+  - Renamed `donna:rfc:work:create` to `donna:rfc:work:request`.
+- gh-58 — Unified error handling in `donna.machine.sessions` and `donna.cli.*` modules.

donna/artifacts/intro.md

@@ -36,3 +36,24 @@ Artifact type tags:
 4. If you are executing a workflow operation and need to perform a complex action or changes, you SHOULD search for an appropriate workflow and run it as a child workflow — it is the intended way to use Donna.
 5. Run to list all workflows: `{{ donna.lib.list("**", tags=["workflow"]) }}`
 6. Run to list all specifications: `{{ donna.lib.list("**", tags=["specification"]) }}`
+
+## Journaling
+
+You MUST use `donna journal write` to track your actions and thoughts, according the description in `{{ donna.lib.view("donna:usage:cli") }}`.
+
+Journaling is a required part of workflow execution. An action request MUST be considered incomplete until required journal records are written.
+
+Journaling lifecycle for each non-trivial action request:
+
+1. Start intent (`Goal:`) before substantial work begins.
+2. Progress updates (`Step:`) at significant phase boundaries.
+3. Concrete edits (`Change:`) after meaningful source/artifact update batches.
+4. Completion handoff (`Step:`) before calling `sessions action-request-completed`.
+
+Journal records MUST be change/decision-oriented and SHOULD be sufficient for another agent to continue work without re-discovery.
+
+If you perform a long operation (e.g., exploring the codebase, designing a solution) that takes more than 10 seconds, you MUST journal your progress.
+
+You MUST use `donna journal view --lines 100` to read the last records after you compress your context.
+
+If your work is interrupted and you resume later, you MUST first journal `Resume context and next action`.

donna/artifacts/rfc/specs/design.md

@@ -0,0 +1,141 @@
+# Format of the Design document
+
+```toml donna
+kind = "donna.lib.specification"
+```
+
+This document describes the format and structure of a Design document used to design changes to a project proposed in a Request for Change (RFC). This document is an input for planning and will be treated as strong recommendations for the implementation of the proposed change.
+
+## Overview
+
+Donna introduces a group of workflows located in `donna:rfc:*` namespace that organize the process of proposing, reviewing, and implementing changes to a project via RFC and Design documents.
+
+You create a Design document to explicitly describe the exact changes you want to make to the project in order to implement the RFC.
+
+If not otherwise specified, Design documents for the session MUST be stored as `session:design:<short-problem-related-identifier>` artifacts in the session world.
+
+**The Design document MUST list exact changes to the project that will be implemented.** E.g. concrete function names and signatures, file paths, data structures, etc.
+
+**The Design document MAY skip implementation details.** E.g. it may skip the exact implementation of a function body, but it should specify the function signature and its purpose; It may use pseudocode to describe the logic of a function, but it should not skip describing the logic at all.
+
+The Design document MUST NOT be a high-level description of the problem and solution. A high-level description of the problem and solution should be provided in the RFC document.
+
+**Identifiers in this document MUST follow project-specific naming conventions.** Before working on a Design document, you should read the artifacts with project guidelines for naming and code style, if any exist.
+
+## Design document structure
+
+The RFC document is Donna artifact (check `{{ donna.lib.view("donna:usage:artifacts") }}`) with the next structure:
+
+- **Primary section** — title and short description of the proposed change.
+- **Inputs** — list of input documents that are relevant for the proposed change, starting from the RFC document.
+- **Architecture changes** — list of high-level architectural changes that MUST be implemented.
+- **Highlevel code changes** — list of high-level code changes that MUST be implemented: modules to add/modify, functions to add/modify, classes to add/modify, etc. This section should not include low-level implementation details, but it should include enough details to understand the scope of the change and its impact on the project.
+- **Data structure changes** — list of changes to data structures that MUST be implemented.
+- **Interface changes** — list of changes to interfaces (e.g. function signatures, API endpoints, etc.) that MUST be implemented.
+- **Tests changes** — list of autotests that MUST be implemented/updated/removed. Only if the project already uses autotests.
+- **Documentation changes** — list of changes in the documentation. Only if the project already has documentation.
+- **Other changes** — list of other changes that do not fit into the previous sections, but are still relevant for the proposed change.
+- **Order of implementation** — a proposed order of implementation of the changes listed in the previous sections. This section should be treated as a recommendation (from the author of the Design document), not a strict requirement.
+
+## General language and format
+
+- You MUST follow [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119.txt) for keywords like MUST, SHOULD, MAY, etc.
+- You MUST follow `{{ donna.lib.view("donna:usage:artifacts") }}`.
+- You MUST follow the structure specified in this document.
+
+### List format
+
+- If a section is described as a list, it MUST contain only a single markdown list.
+- Each list item MUST be concise and clear.
+- Each list item SHOULD be atomic and focused on a single aspect.
+- Reviewer MUST be able to tell whether the list item statement is true or false by inspecting the resulting artifacts and behavior.
+
+Examples:
+
+- Bad: `- Implement a new module.`
+- Bad: `- The interface MUST include button A, button B, and dropdown C.`
+- Good: `- Implement a module "a.b.c" that is responsible for X, Y, and Z.`
+- Good: `- Add a button class "ButtonA" to the module "a.b.c"`
+- Good: `- "ButtonA" class MUST have a method "click()" that performs action X when called.`
+
+Common approaches to improve list items:
+
+- Split a single item with an enumeration into multiple items with a single focus.
+- Transform an abstract item into a concrete one by specifying measurable criteria or user-visible behavior.
+
+## `Primary` section
+
+- Title MUST be concise and reflect the essence of the proposed change. Derive it from the RFC.
+- Description MUST provide an essence of the proposed change.
+
+## `Inputs` section
+
+- The section MUST contain a list of documents that are relevant to the proposed change.
+- The first item in the list MUST be the original RFC document that describes the problem and the proposed solution.
+- Other items in the list MAY include other documentation, code files, external links, etc., that are relevant for the proposed change.
+
+## `Architecture changes` section
+
+- The section MUST contain a free-form but precise and grounded description of the high-level architectural changes that MUST be implemented.
+- Along the text, you may add code snippets, diagrams, and other visual aids to make the description clearer and more precise.
+
+## `High-level code changes` section
+
+- The section MUST contain a list of high-level changes in the code.
+- The level of abstraction: `add a module A`, `remove the class B`, `change the implementation of a function C`.
+- The section MUST list only the most important changes that are significant cornerstones of the proposed change.
+- The section MAY omit low-level details, such as the small or utilitarian functions, minor refactorings, etc.
+
+## `Data structure changes` section
+
+- The section MUST list exact changes to data structures that MUST be implemented.
+- Each change MUST be accompanied by a description of the purpose of the change and its impact on the project.
+
+Examples of statements about structure changes:
+
+- Bad: `- Change the data structure of the project.`
+- Bad: `- Update the class A.`
+- Good: `- Add a field "x" to the class "A".`
+- Good: `- Change the type of the field "y" in the class "B" from "int" to "str".`
+- Good: `- Add structure "C" with fields "a", "b", and "c".`
+
+## `Interface changes` section
+
+- The section MUST list exact changes to interfaces that MUST be implemented.
+- Each change MUST be accompanied by a description of the purpose of the change and its impact on the project.
+
+Examples of statements about interface changes:
+
+- Bad: `- Change the interface of functions in the project.`
+- Bad: `- Update the API endpoints.`
+- Good: `- Add a new API endpoint "/api/v1/resource" that accepts POST requests with JSON body containing fields "a", "b", and "c".`
+- Good: `- Change the signature of the function "foo" from "foo(x: int) -> str" to "foo(x: int, y: str) -> str".`
+
+## `Tests changes` section
+
+- If the project does not use autotests, this section MUST contain a statement `No changes in tests are required, since the project does not use autotests.`
+- If the project uses autotests, this section MUST contain a list of autotests that MUST be implemented/updated/removed.
+- Each changes piece of logic MUST have at least one corresponding autotest that verifies its correctness and prevents regressions in the future.
+- Each added/updated branch of logic MUST have at least one corresponding autotest that verifies its correctness and prevents regressions in the future.
+
+Examples of statements about test changes:
+
+- Bad: `- Add tests for the new module.`
+- Bad: `- Update tests for the changed function.`
+- Good: `- Add a test "test_foo_with_valid_input" that verifies that the function "foo" returns the expected result when called with valid input.`
+- Good: `- Add a test "test_foo_success_path" that verifies that the function "foo" returns the expected result when called with input that follows the success path.`
+
+## `Documentation changes` section
+
+- If the project does not have documentation, this section MUST contain a statement `No changes in documentation are required, since the project does not have documentation.`
+- If the project has documentation, this section MUST contain a list of changes in the documentation that MUST be implemented.
+
+## `Other changes` section
+
+- The section MAY contain a list of other changes that do not fit into the previous sections, but are still relevant for the proposed change.
+- The section MUST be a single statement: `No other changes are required, since all relevant changes are covered in the previous sections.` if there are no other changes to mention.
+
+## `Order of implementation` section
+
+- The section MUST contain a proposed order of implementation of the changes listed in the previous sections.
+- The section MUST refer only to identifiers mentioned in the previous sections, and it MUST NOT introduce new identifiers or entities that are not mentioned in the previous sections.

donna/artifacts/rfc/specs/request_for_change.md

@@ -4,20 +4,16 @@
 kind = "donna.lib.specification"
 ```
 
-This document describes the format and structure of a Request for Change (RFC) document used to propose changes to a project by Donna workflows from `donna:rfc:*` namespace.
+This document describes the format and structure of a Request for Change (RFC) document used to propose changes to a project by Donna workflows from `donna:rfc:*` namespace. This document is an input for a Design document creation.
 
 ## Overview
 
-Donna introduces a group of workflows located in `donna:rfc:*` namespace that organize the process of proposing, reviewing, and implementing changes to a project via RFC documents.
+Donna introduces a group of workflows located in `donna:rfc:*` namespace that organize the process of proposing, reviewing, and implementing changes to a project via RFC and Design documents.
 
 You create RFC documents to propose changes to the project.
 
 If not otherwise specified, RFC documents for the session MUST be stored as `session:rfc:<short-problem-related-identifier>` artifacts in the session world.
 
-The agent (via workflows) creates the artifact and polishes it iteratively as the RFC process progresses.
-
-After the RFC is completed, the agent (via workflows) MAY implement changes directly or create and execute a workflow based on the RFC content.
-
 ## RFC structure
 
 The RFC document is Donna artifact (check `{{ donna.lib.view("donna:usage:artifacts") }}`) with the next structure:

donna/artifacts/rfc/work/design.md

@@ -0,0 +1,121 @@
+# Create a Design document
+
+```toml donna
+kind = "donna.lib.workflow"
+start_operation_id = "start"
+```
+
+This workflow creates a Design document artifact based on an RFC and aligned with `donna:rfc:specs:design`.
+
+## Start Work
+
+```toml donna
+id = "start"
+kind = "donna.lib.request_action"
+fsm_mode = "start"
+```
+
+1. Read the specification `{{ donna.lib.view("donna:rfc:specs:design") }}` if you haven't done it yet.
+2. Read the specification `{{ donna.lib.view("donna:usage:artifacts") }}` if you haven't done it yet.
+3. `{{ donna.lib.goto("ensure_rfc_artifact_exists") }}`
+
+## Ensure RFC artifact exists
+
+```toml donna
+id = "ensure_rfc_artifact_exists"
+kind = "donna.lib.request_action"
+```
+
+At this point, you SHOULD have a clear RFC to design.
+
+1. If you have an RFC artifact id in your context, view it and `{{ donna.lib.goto("prepare_design_artifact") }}`.
+2. If you have no RFC artifact id in your context, but you know it is in one of `{{ donna.lib.list("session:**") }}` artifacts, find and view it. Then `{{ donna.lib.goto("prepare_design_artifact") }}`.
+3. If you have no RFC artifact id in your context, and you don't know where it is, ask the developer to provide the RFC artifact id or to create a new RFC. After you get it and view the artifact, `{{ donna.lib.goto("prepare_design_artifact") }}`.
+
+## Prepare Design artifact
+
+```toml donna
+id = "prepare_design_artifact"
+kind = "donna.lib.request_action"
+```
+
+1. If the name of the artifact is not specified explicitly, assume it to be `session:design:<short-problem-related-identifier>`, where `<short-problem-related-identifier>` SHOULD correspond to the RFC slug.
+2. Save the next template into the artifact, replace `<variables>` with appropriate values.
+
+~~~
+# <Title>
+
+```toml donna
+kind = "donna.lib.specification"
+```
+
+<short description of the proposed design>
+
+## Inputs
+
+- <RFC artifact id>
+
+## Architecture changes
+
+## High-level code changes
+
+## Data structure changes
+
+## Interface changes
+
+## Tests changes
+
+## Documentation changes
+
+## Other changes
+
+## Order of implementation
+~~~
+
+3. `{{ donna.lib.goto("initial_fill") }}`
+
+## Initial Fill
+
+```toml donna
+id = "initial_fill"
+kind = "donna.lib.request_action"
+```
+
+1. Read the specification `{{ donna.lib.view("donna:rfc:specs:design") }}` if you haven't done it yet.
+2. Read the RFC artifact selected in the previous step if you haven't done it yet.
+3. Analyze the project if needed to understand the requested change context.
+4. Fill in all sections of the Design draft artifact.
+5. Ensure the first item in `Inputs` section is the RFC artifact id.
+6. `{{ donna.lib.goto("review_design_format") }}`
+
+## Review Design Format
+
+```toml donna
+id = "review_design_format"
+kind = "donna.lib.request_action"
+```
+
+1. List mismatches between the Design artifact and the Design specification `{{ donna.lib.view("donna:rfc:specs:design") }}`.
+2. For each mismatch, make necessary edits to the Design draft artifact to ensure compliance.
+3. `{{ donna.lib.goto("review_design_content") }}`
+
+## Review Design Content
+
+```toml donna
+id = "review_design_content"
+kind = "donna.lib.request_action"
+```
+
+1. Read the Design document and identify gaps, inconsistencies, or areas for improvement in accordance with the RFC and current project context. Use `{{ donna.lib.view("donna:research:work:research") }}` workflow if you need to make a complex decision.
+2. Make necessary edits to the Design draft artifact to address identified issues.
+3. If there were changes made on this step or the previous `review_design_format` step `{{ donna.lib.goto("review_design_format") }}`.
+4. If no changes were made, `{{ donna.lib.goto("finish") }}`.
+
+## Complete Draft
+
+```toml donna
+id = "finish"
+kind = "donna.lib.finish"
+```
+
+Design draft is complete and ready for implementation planning.