donna 0.2.1__py3-none-any.whl → 0.2.3__py3-none-any.whl

donna/artifacts/intro.md

@@ -1,4 +1,4 @@
-# Intoduction to the Donna tool
+# Introduction to the Donna tool
 
 ```toml donna
 kind = "donna.lib.specification"
@@ -21,7 +21,7 @@ We may need coding agents on the each step of the process, but there no reason f
 
 ## Artifact Tags
 
-To simplicity searching of artifacts by their semantics, Donna allows tagging artifacts with semantically valuable keywords. Artifacts in `donna:*` world use the next set of tags.
+To simplify searching for artifacts by their semantics, Donna allows tagging artifacts with semantically valuable keywords. Artifacts in `donna:*` world use the next set of tags.
 
 Artifact type tags:
 

donna/artifacts/research/specs/report.md

@@ -12,7 +12,7 @@ Donna introduces a group of workflows located in `donna:research:*` namespace th
 
 Session-related research artifacts MUST be stored as `session:research:<short-problem-related-identifier>`, unless the developer or parent workflow specifies a different location. The `<short-problem-related-identifier>` MUST be unique within the session.
 
-Agent (via workflows) creates that artifact and updates it iteratively as the research process goes on.
+The agent (via workflows) creates the artifact and updates it iteratively as the research process progresses.
 
 ## Research report structure
 
@@ -40,14 +40,14 @@ The research report is a Donna artifact (check `{{ donna.lib.view("donna:usage:a
 
 ### List format
 
-- If a section described as a list, it MUST contain only a single markdown list.
+- 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 if the list item statement is true or false by inspecting resulting artifacts and behavior.
+- Reviewer MUST be able to tell if the list item statement is true or false by inspecting the resulting artifacts and behavior.
 
 Common approaches to improve list items:
 
-- Split a single item with an enumeration into multiple items with single focus.
+- Split a single item with an enumeration into multiple items with a single focus.
 - Transform an abstract item into a concrete one by referencing specific artifacts, measurable criteria, verifiable conditions, etc.
 
 ### Trusted inputs
@@ -57,9 +57,9 @@ Some sections of the research report MUST be based on trusted inputs. Trusted in
 - Original problem description from the developer or parent workflow.
 - Statements from the research report itself.
 - Existing project documentation, code, and artifacts.
-- External standards when they define constraints or best practices for the project domain.
-- Documentation of third-party libraries, frameworks, or tools when it describes constraints or best practices.
-- Primary research sources (datasets, reports, official publications) used to collect the required information.
+- External standards, when they define constraints or best practices for the project domain.
+- Documentation of third-party libraries, frameworks, or tools when they describe constraints or best practices.
+- Primary research sources (datasets, reports, official publications) were used to collect the required information.
 
 ## `Primary` section
 

donna/artifacts/research/work/research.md

@@ -9,7 +9,7 @@ Workflow for performing research on a given question/problem/situation. Collects
 
 The purpose of this workflow is to provide an information for making decisions or producing solutions based on researched data. It can be used:
 
-- When the developer explicitly asks to make a research.
+- When the developer explicitly asks to conduct research.
 - When other workflows need to perform research as a subtask.
 
 ## Start
@@ -31,7 +31,7 @@ id = "ensure_problem_description_exists"
 kind = "donna.lib.request_action"
 ```
 
-At this point you SHOULD have a clear description of the problem in your context. I.e. you know what you need to do in this workflow.
+At this point, you SHOULD have a clear description of the problem in your context. I.e., you know what you need to do in this workflow.
 
 1. If you have a problem description in your context, `{{ donna.lib.goto("prepare_artifact") }}`.
 2. If you have no problem description in your context, but you know it is in one of `session:*` artifacts, find and view it. Then `{{ donna.lib.goto("prepare_artifact") }}`.
@@ -99,9 +99,9 @@ id = "describe_solution_space"
 kind = "donna.lib.request_action"
 ```
 
-To produce solution we should understand how to analyze the data and how to synthesize results into the final solution.
+To produce a solution, we should understand how to analyze the data and how to synthesize results into the final solution.
 
-For this we need to list the axes along which we will analyze the data and the dimensions along which we will synthesize the results.
+For this, we need to list the axes along which we will analyze the data and the dimensions along which we will synthesize the results.
 
 1. List the analysis axes.
 2. List the synthesis dimensions.
@@ -151,7 +151,7 @@ id = "analyze_information"
 kind = "donna.lib.request_action"
 ```
 
-1. Using the analysis axes from the solution space description, analyze the collected information. Choose the format that best represents the analysis results and suits the the required solution form.
+1. Using the analysis axes from the solution space description, analyze the collected information. Choose the format that best represents the analysis results and suits the required solution form.
 2. Update the artifact with the analysis results.
 3. `{{ donna.lib.goto("synthesize_solutions") }}`
 
@@ -162,7 +162,7 @@ id = "synthesize_solutions"
 kind = "donna.lib.request_action"
 ```
 
-1. Using the synthesis dimensions from the solution space description, synthesize possible solutions based on the analysis results. Choose the format that best represents the synthesized solutions and suits the the required solution form.
+1. Using the synthesis dimensions from the solution space description, synthesize possible solutions based on the analysis results. Choose the format that best represents the synthesized solutions and suits the required solution form.
 2. Update the artifact with the synthesized solutions.
 3. `{{ donna.lib.goto("evaluate_solutions") }}`
 

donna/artifacts/rfc/specs/request_for_change.md

@@ -10,13 +10,13 @@ This document describes the format and structure of a Request for Change (RFC) d
 
 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.
 
-You create RFC documents to propose changes to the project
+You create RFC documents to propose changes to the project.
 
-If there is not specified otherwise, RFC documents for the session MUST be stored as `session:rfc:<short-problem-related-identifier>` artifacts in the session world.
+If not otherwise specified, RFC documents for the session MUST be stored as `session:rfc:<short-problem-related-identifier>` artifacts in the session world.
 
-Agent (via workflows) creates that artifact and polishes it iteratively as the RFC process goes on.
+The agent (via workflows) creates the artifact and polishes it iteratively as the RFC process progresses.
 
-After the RFC is completed, agent (via workflows) MAY implement changes directly or by creating and executing a workflow based on the RFC content.
+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
 
@@ -43,23 +43,23 @@ The RFC document is Donna artifact (check `{{ donna.lib.view("donna:usage:artifa
 
 ### List format
 
-- If a section described as a list, it MUST contain only a single markdown list.
+- 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 is the list item statement true or false by inspecting resulting artifacts and behavior.
+- Reviewer MUST be able to tell whether the list item statement is true or false by inspecting the resulting artifacts and behavior.
 
 Examples:
 
 - Bad: `- Improve performance and fix bugs.`
 - Bad: `- The interface MUST include button A, button B, and dropdown C.`
 - Good: `- Performance test MUST show at least 20% improvement in response time under load.`
-- Good: `- Fix bug A causing crash when input is empty.`
+- Good: `- Fix bug A causing a crash when input is empty.`
 - Good: `- The interface MUST include button A that triggers action X.`
 - Good: `- The interface MUST include button B that triggers action Y.`
 
 Common approaches to improve list items:
 
-- Split a single item with an enumeration into multiple items with single focus.
+- 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.
 
 ### Trusted inputs
@@ -69,8 +69,8 @@ Some sections of the RFC document MUST be based on trusted inputs. Trusted input
 - Original description from the developer or parent workflow.
 - Statements from the RFC document itself.
 - Existing project documentation, code, and artifacts.
-- External standards when they define constraints or best practices for the project domain.
-- Documentation of third-party libraries, frameworks, or tools when it describes constraints or best practices.
+- External standards, when they define constraints or best practices for the project domain.
+- Documentation of third-party libraries, frameworks, or tools when they describe constraints or best practices.
 
 ## `Primary` section
 
@@ -84,10 +84,9 @@ Some sections of the RFC document MUST be based on trusted inputs. Trusted input
 
 ## `Formal description` section
 
-- The section MUST contain a clear professional high-level description of the work to be done based
-  on the developer's request.
+- The section MUST contain a clear professional high-level description of the work to be done based on the developer's request.
 - The section MUST be limited to a single paragraph with a few sentences.
-- The sectino MUST explain what someone gains after these changes and how they can see it working.
+- The section MUST explain what someone gains after these changes and how they can see it working.
   State the user-visible behavior the change will enable.
 
 ## `Goals` section
@@ -96,7 +95,7 @@ Some sections of the RFC document MUST be based on trusted inputs. Trusted input
 
 The goal quality criteria:
 
-- A goal MUST be a desired end state, outcome or result.
+- A goal MUST be a desired end state, outcome, or result.
 - A goal MUST define what ultimately should be true, not how to achieve it.
 
 Examples:
@@ -141,7 +140,7 @@ Examples:
 - Bad: `- Use clean architecture.`
 - Good: `- The solution MUST be compatible with Python 3.12.`
 - Good: `- The solution MUST NOT introduce new runtime dependencies.`
-- Good: `- The solution MUST follow specification project:specs:abc`
+- Good: `- The solution MUST follow the specification project:specs:abc`
 - Good: `MUST not change public CLI flags`
 
 ## `Requirements` section
@@ -165,12 +164,12 @@ Examples:
 ## `Acceptance criteria` section
 
 - The section MUST contain a list of acceptance criteria used to determine whether the proposed change is complete and successful.
-- An acceptance criterion MUST be derived explictily from statements in the RFC document. Agents MUST NOT invent acceptance criteria.
+- An acceptance criterion MUST be derived explicitly from statements in the RFC document. Agents MUST NOT invent acceptance criteria.
 
 Acceptance criteria quality criteria:
 
 - An acceptance criterion MUST be a single atomic check that results in a pass/fail outcome.
-- An acceptance criterion check MUST be about a single artifact: single file exists, single test passes, single behavior observed, etc.
+- An acceptance criterion check MUST be about a single artifact: a single file exists, a single test passes, a single behavior observed, etc.
 - An acceptance criterion MUST NOT describe implementation steps, internal design decisions, or "how" to achieve the result.
 
 Examples:
@@ -192,7 +191,7 @@ Solution statement quality criteria:
 
 - A solution statement MUST be a specific change in a specific artifact, behavior, or capability.
 - A solution statement MUST NOT prescribe implementation steps.
-- A solution statement SHOULD be phrased in present tense, describing an achieved state.
+- A solution statement SHOULD be phrased in the present tense, describing an achieved state.
 
 Examples:
 
@@ -231,7 +230,7 @@ Examples:
 
 Deliverable quality criteria:
 
-- A deliverable MUST be a tangible a single artifact or a single part of an artifact, not an activity or process.
+- A deliverable MUST be a tangible, single artifact or a single part of an artifact, not an activity or process.
 - A deliverable MUST be independently identifiable and verifiable.
 - Each deliverable MUST be phrased as an existence statement using normative
   language: "MUST include …", "MUST exist …", etc.

donna/artifacts/rfc/work/create.md

@@ -6,7 +6,7 @@ kind = "donna.lib.workflow"
 start_operation_id = "start"
 ```
 
-This workflow creates a Request for Change (RFC) document based on a description of a problem or changes required.
+This workflow creates a Request for Change (RFC) document based on a description of the problem or the required changes.
 
 ## Start Work
 
@@ -27,7 +27,7 @@ id = "ensure_work_description_exists"
 kind = "donna.lib.request_action"
 ```
 
-At this point you SHOULD have a clear description of the problem in your context. I.e. you know what you need to do in this workflow.
+At this point, you SHOULD have a clear description of the problem in your context. I.e. you know what you need to do in this workflow.
 
 1. If you have a problem description in your context, `{{ donna.lib.goto("prepare_rfc_artifact") }}`.
 2. If you have no problem description 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_rfc_artifact") }}`.
@@ -40,7 +40,7 @@ id = "prepare_rfc_artifact"
 kind = "donna.lib.request_action"
 ```
 
-1. If the name of artifact is not specified explicitly, assume it to be `session:rfc:<short-problem-related-identifier>`, where `<short-problem-related-identifier>` MUST be unique within the session.
+1. If the name of the artifact is not specified explicitly, assume it to be `session:rfc:<short-problem-related-identifier>`, where `<short-problem-related-identifier>` MUST be unique within the session.
 2. Save the next template into the artifact, replace `<variables>` with appropriate values.
 
 ```
@@ -105,7 +105,7 @@ id = "review_rfc_content"
 kind = "donna.lib.request_action"
 ```
 
-1. Read the RFC document and identify any gaps, inconsistencies, or areas for improvement in the content in accordance with the current project context. Use `{{ donna.lib.view("donna:research:work:research") }}` workflow if you need to take a complex decision.
+1. Read the RFC document and identify any gaps, inconsistencies, or areas for improvement in the content in accordance with the 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 RFC draft artifact to address identified issues.
 3. If there were changes made on this step or the previous `review_rfc_format` step `{{ donna.lib.goto("review_rfc_format") }}`.
 4. If no changes were made, `{{ donna.lib.goto("finish") }}`.

donna/artifacts/rfc/work/do.md

@@ -20,12 +20,12 @@ kind = "donna.lib.request_action"
 ```
 
 1. If the developer or parent workflow explicitly specified that the work is complex, `{{ donna.lib.goto("create_rfc") }}`.
-2. If the developer or parent workflow explicitly specified that the work is simple, `{{ donna.lib.goto("fast_planing") }}`.
+2. If the developer or parent workflow explicitly specified that the work is simple, `{{ donna.lib.goto("fast_planning") }}`.
 3. Make a rough estimate of the complexity of the requested changes.
-4. If the complexity is small, `{{ donna.lib.goto("fast_planing") }}`.
+4. If the complexity is small, `{{ donna.lib.goto("fast_planning") }}`.
 5. Otherwise, `{{ donna.lib.goto("create_rfc") }}`.
 
-Examles of changes with small complexity:
+Examples of changes with small complexity:
 
 - A single file edit with clear instructions.
 - A small addition to an existing function or class.
@@ -33,10 +33,10 @@ Examles of changes with small complexity:
 - A small documentation update.
 - A simple bug fix with a known solution.
 
-## Fast planing
+## Fast planning
 
 ```toml donna
-id = "fast_planing"
+id = "fast_planning"
 kind = "donna.lib.request_action"
 ```
 
@@ -62,9 +62,9 @@ id = "plan_rfc_work"
 kind = "donna.lib.request_action"
 ```
 
-1. Choose the workflow to plan the work required to implement the RFC created on the previous step.
+1. Choose the workflow to plan the work required to implement the RFC created in the previous step.
 2. Run the chosen workflow.
-3. Ensure you know the workflow id created in the previous step (default is `session:exectute_rfc` if not specified).
+3. Ensure you know the workflow id created in the previous step (default is `session:execute_rfc` if not specified).
 4. After completing the workflow `{{ donna.lib.goto("execute_rfc_work") }}`.
 
 ## Execute RFC work
@@ -74,7 +74,7 @@ id = "execute_rfc_work"
 kind = "donna.lib.request_action"
 ```
 
-1. Run the workflow created by the plan step (default: `session:exectute_rfc`) and complete it.
+1. Run the workflow created by the plan step (default: `session:execute_rfc`) and complete it.
 2. After completing the workflow `{{ donna.lib.goto("polish_changes") }}`.
 
 ## Polish changes

donna/artifacts/rfc/work/plan.md

@@ -16,7 +16,7 @@ kind = "donna.lib.request_action"
 fsm_mode = "start"
 ```
 
-1. Read the RFC the developer or parent workflow want you to implement.
+1. Read the RFC that the developer or parent workflow wants you to implement.
 2. Read the specification `{{ donna.lib.view("donna:usage:artifacts") }}` if you haven't done it yet.
 2. `{{ donna.lib.goto("prepare_workflow_artifact") }}`
 
@@ -27,15 +27,15 @@ id = "prepare_workflow_artifact"
 kind = "donna.lib.request_action"
 ```
 
-1. If the name of artifact is not specified explicitly, assume it to `session:plans:<short-id-equal-to-rfc-slug>`.
+1. If the name of the artifact is not specified explicitly, assume it to `session:plans:<short-id-equal-to-rfc-slug>`.
 2. Create a workflow with the next operations:
    - Start
    - A step for each action point in the RFC, ordered to minimize dependencies between steps and introduce changes incrementally.
-   - (`id="review_changes"`) A gate step to start review the changes.
-   - A gate step to start review the deliverables.
-   - A step per deliverable to check if it exists and is correct. If the deliverable is missing or incorrect, step MUST specify how to fix it an goto to `review_changes` step.
+   - (`id="review_changes"`) A gate step to start reviewing the changes.
+   - A gate step to start reviewing the deliverables.
+   - A step per deliverable to check if it exists and is correct. If the deliverable is missing or incorrect, the step MUST specify how to fix it and `goto` to the `review_changes` step.
    - A gate step to start verification.
-   - A step for each verification statement to check it. If the statement is not satisfied, step MUST specify how to fix it and goto to the `review_changes` step.
+   - A step for each verification statement to check it. If the statement is not satisfied, the step MUST specify how to fix it and `goto` to the `review_changes` step.
    - A finish step.
 3. `{{ donna.lib.goto("review_workflow") }}`
 
@@ -46,16 +46,16 @@ id = "review_workflow"
 kind = "donna.lib.request_action"
 ```
 
-For each of steps in the workflow you created:
+For each of the steps in the workflow you created:
 
-1. If the step can fail, add instructions on how to fix the issue and goto to appropriate step.
+1. If the step can fail, add instructions on how to fix the issue and `goto` to the appropriate step.
 2. If the step requires both research and implementation, split it into two steps: research step and implementation step.
 3. If the step required editing multiple artifacts (multiple files, multiple functions, etc.), split it into multiple steps, one per change required.
 4. If the step is too big or complex, split it into multiple smaller steps.
 
 After all steps are reviewed:
 
-1. If the changes where introduced, `{{ donna.lib.goto("review_workflow") }}`.
+1. If the changes were introduced, `{{ donna.lib.goto("review_workflow") }}`.
 2. If no changes were introduced, `{{ donna.lib.goto("finish") }}`.
 
 ## Finish

donna/artifacts/usage/artifacts.md

@@ -28,11 +28,11 @@ Read the specification `{{ donna.lib.view("donna:usage:cli") }}` to learn how to
 
 ## Source Format and Rendering
 
-The source of the text artifact is a Jinja2-template of Markdown document.
+The source of the text artifact is a Jinja2 template of a Markdown document.
 
 When rendering the artifact, Donna processes the Jinja2 template with a predefined context (at minimum `render_mode` and `artifact_id`, and optionally `current_task`/`current_work_unit` during workflow execution), then renders the resulting Markdown content into the desired representation based on the selected rendering mode.
 
-**Artifact source should not use Jinja2 inheretance features** like `{{ "{% extends %}" }}` and `{{ "{% block %}" }}`.
+**Artifact source should not use Jinja2 inheritance features** like `{{ "{% extends %}" }}` and `{{ "{% block %}" }}`.
 
 Donna provides a set of special directives that can and MUST be used in the artifact source to enhance its behavior. Some of these directives are valid for all artifacts, some are valid only for specific section kinds.
 
@@ -63,11 +63,11 @@ Donna renders the same artifact source into different representations depending
 
 Technically, any valid Markdown document is a valid text artifact.
 
-However, Donna assignes special meaning to some elements of the Markdown document to provide enhanced behavior and capabilities.
+However, Donna assigns special meaning to some elements of the Markdown document to provide enhanced behavior and capabilities.
 
 ### Sections
 
-Artifact is devided into multiple sections:
+Artifact is divided into multiple sections:
 
 - H1 header and all text till the first H2 header is considered the `head section` of the artifact.
 - Each H2 header and all text till the next H2 header (or end of document) is considered a `tail section` of the artifact.
@@ -170,7 +170,9 @@ kind = "donna.lib.request_action"
 
 #### Kinds of Workflow Operations
 
-1. `donna.lib.request_action` operation kind indicates that Donna will request the agent to perform some action.
+##### `donna.lib.request_action`
+
+`donna.lib.request_action` operation kind indicates that Donna will request the agent to perform some action.
 
 The content of the tail section is the text instructions for the agent on what to do.
 
@@ -188,7 +190,9 @@ Here may be any additional instructions, requirements, notes, references, etc.
 
 **The body of the operation MUST contain a neat strictly defined algorithm for the agent to follow.**
 
-2. `donna.lib.run_script` operation kind executes a script from the operation body without agent/user interaction.
+##### `donna.lib.run_script`
+
+`donna.lib.run_script` operation kind executes a script from the operation body without agent/user interaction.
 
 The body of the operation MUST include exactly one fenced code block whose info string includes `<language> donna script`.
 Any other text in the operation body is ignored.
@@ -229,7 +233,9 @@ Routing rules:
 When `save_stdout_to` and/or `save_stderr_to` are set, the operation stores captured output in the task context
 under the specified variable names.
 
-3. `donna.lib.output` operation kind emits its body as an output cell and then continues to the configured next step.
+##### `donna.lib.output`
+
+`donna.lib.output` operation kind emits its body as an output cell and then continues to the configured next step.
 
 The body of the operation is rendered as an output cell during execution.
 
@@ -241,7 +247,9 @@ kind = "donna.lib.output"
 next_operation_id = "<next_operation_id>"  # required
 ```
 
-4. `donna.lib.finish` operation kind indicates that the workflow is finished.
+##### `donna.lib.finish`
+
+`donna.lib.finish` operation kind indicates that the workflow is finished.
 
 The body of the operation is rendered as an output cell before the workflow completes.
 
@@ -254,6 +262,6 @@ Donna provides multiple directives that MUST be used in the artifact source to e
 Here they are:
 
 1. `{{ "{{ donna.lib.view(<artifact-id-pattern>) }}" }}` — references another artifact (supports `*` and `**` wildcard patterns). In `view`/`execute` modes it renders an exact CLI command to view the artifact; in `analysis` mode it renders a `$$donna ... $$` marker.
-2. `{{ "{{ donna.lib.list(<artifact-id-pattern>) }}" }}` — references artifact listing by pattern (supports `*` and `**` wildcard patterns). In `view`/`execute` modes it renders an exact CLI command to list artifacts; in `analysis` mode it renders a `$$donna ... $$` marker.
-3. `{{ "{{ donna.lib.goto(<workflow-operation-id>) }}" }}` — references the next workflow operation to execute. In `view`/`execute` modes it renders an exact CLI command to advance the workflow; in `analysis` mode it renders a `$$donna goto ... $$` marker used for transition extraction.
+2. `{{ "{{ donna.lib.list(<artifact-id-pattern>) }}" }}` — references artifact listing by pattern (supports `*` and `**` wildcard patterns). In `view`/`execute` modes it renders an exact CLI command to list artifacts; in `analysis` mode, it renders a `$$donna ... $$` marker.
+3. `{{ "{{ donna.lib.goto(<workflow-operation-id>) }}" }}` — references the next workflow operation to execute. In `view`/`execute` modes it renders an exact CLI command to advance the workflow; in `analysis` mode, it renders a `$$donna goto ... $$` marker used for transition extraction.
 4. `{{ "{{ donna.lib.task_variable(<variable_name>) }}" }}` — in `view` mode renders a placeholder note about task-variable substitution, in `execute` mode renders the actual task-context value (or an explicit error marker if missing), and in `analysis` mode renders a `$$donna task_variable ... $$` marker.

donna/artifacts/usage/cli.md

@@ -59,7 +59,7 @@ action_request_id=AR-65-bd
 --DONNA-CELL eZVkOwNPTHmadXpaHDUBNA END--
 ```
 
-Donna can ommit log cell start and end markers if a command produces only a single cell.
+Donna can omit log cell start and end markers if a command produces only a single cell.
 
 Donna renders cells differently, depending on the protocol used.
 
@@ -68,7 +68,7 @@ Donna renders cells differently, depending on the protocol used.
 There are three sets of commands:
 
 - `donna -p <protocol> workspaces …` — manages workspaces. Most-likely it will be used once per your project to initialize it.
-- `donna -p <protocol> sessions …` — manages sessions. You will use these commands to start, push forward, and manage your work sessions.
+- `donna -p <protocol> sessions …` — manages sessions. You will use these commands to start, push forward, and manage your work.
 - `donna -p <protocol> artifacts …` — manages artifacts. You will use these commands to read and update artifacts you are working with.
 
 Use:
@@ -82,31 +82,37 @@ Run `donna -p <protocol> workspaces init [<directory-path>]` to initialize Donna
 
 It is a one time operation you need to perform once per project to create a place where Donna will store all its data.
 
-### Session flow
+### Starting sessions
+
+The developer is responsible for starting a new session.
+
+You are allowed to start a new session in the next cases:
+
+1. There is no active session.
+2. The developer explicitly instructed you to start a new session.
 
 You start session by calling `donna -p <protocol> sessions start`.
 
-After you started a session:
+### Session flow
+
+After the session starts you MUST follow the next workflow to perform your work:
 
 1. List all possible workflows with command `donna -p <protocol> artifacts list`.
 2. Choose the most appropriate workflow for the task you are going to work on or ask the developer if you are not sure which workflow to choose.
-3. Start choosen workflow by calling `donna -p <protocol> sessions run <workflow-id>`.
+3. Start chosen workflow by calling `donna -p <protocol> sessions run <workflow-id>`.
 4. Donna will output descriptions of all operations it performs to complete the work.
 5. Donna will output **action requests** that you MUST perform. You MUST follow these instructions precisely.
 6. When you done processing an action request, call `donna -p <protocol> sessions action-request-completed <action-request-id> <next-full-operation-id>` to report request completion. `<next-full-operation-id>` MUST contain full identifier of the next operation, like `<world>:<artifact>:<operation-id>`.
-7. After you complete an action request, Donna will continue workflow execution and outputs what you need to do next.
+7. After you complete an action request, Donna will continue workflow execution and output what you need to do next.
 
 You MUST continue following Donna's instructions until the workflow is completed.
 
 ### Session state
 
-You may run `donna -p <protocol> sessions status` to get the status of the current session.
-
-You may run `donna -p <protocol> sessions details` to get detailed information about the current session, including list of active action requests.
-
-Run `donna -p <protocol> sessions start` to start fully new session. This command resets session state AND removes all session-level artifacts. Use this command when you need to start work from scratch.
-
-Run `donna -p <protocol> sessions reset` to reset the current session. This command resets session state BUT keeps all session-level artifacts. Use this command when you need to restart the worklow but keep all the artifacts you created during the session.
+- `donna -p <protocol> sessions status` — get the status of the current session.
+- `donna -p <protocol> sessions details` — get detailed information about the current session, including list of active action requests.
+- `donna -p <protocol> sessions start` — start a new session. This command resets session state AND removes all session-level artifacts.
+- Run `donna -p <protocol> sessions reset` to reset the current session. This command resets session state BUT keeps all session-level artifacts. Use this command when you need to restart the worklow but keep all the artifacts you created during the session.
 
 ### Starting work
 
@@ -114,8 +120,8 @@ If the developer asked you to do something new:
 
 - Run `donna -p <protocol> sessions status` to get the status of the current session.
 - If there is no active session, start a new session by calling `donna -p <protocol> sessions start`.
-- If the session is already active and there are no unfinished work in it, start a new session by calling `donna -p <protocol> sessions start`.
-- If the session is already active and there are unfinished work in it, you MUST ask the developer whether to continue the work in the current session or start a new one.
+- If the session is active and there are unfinished work in it, you MUST ask the developer whether to continue the work in the current session or start a new one.
+- If the session is active and there are no unfinished work in it, follow the instructions in the `Session flow` section to choose and start a new workflow.
 
 ### Continuing work
 
@@ -127,11 +133,11 @@ If Donna tells you there is no work left, you MUST inform the developer that the
 
 An artifact is a markdown document with extra metadata stored in one of the Donna's worlds.
 
-Use the next commands to work with artifacts
+Use the next commands to work with artifacts:
 
 - `donna -p <protocol> artifacts list [<artifact-pattern>]` — list all artifacts corresponding to the given pattern. If `<artifact-pattern>` is omitted, list all artifacts in all worlds. Use this command when you need to find an artifact or see what artifacts are available.
 - `donna -p <protocol> artifacts view <artifact-pattern>` — get the meaningful (rendered) content of all matching artifacts. This command shows the rendered information about each artifact. Use this command when you need to read artifact content.
-- `donna -p <protocol> artifacts fetch <world>:<artifact>` — download the original source of the artifact content, outputs the file path to the artifact's copy you can change. Use this command when you need to change the content of the artifact.
+- `donna -p <protocol> artifacts fetch <world>:<artifact>` — download the original source of the artifact content, outputs the file path to the artifact's copy, you can change. Use this command when you need to change the content of the artifact.
 - `donna -p <protocol> artifacts tmp <slug>.<extension>` — create a temporary file for artifact-related work and output its path.
 - `donna -p <protocol> artifacts update <world>:<artifact> <file-path>` — upload the given file as the artifact. Use this command when you finished changing the content of the artifact.
 - `donna -p <protocol> artifacts copy <artifact-id-from> <artifact-id-to>` — copy an artifact source to another artifact ID (can be in a different world). This overwrites the destination if it exists.

donna/cli/commands/sessions.py

@@ -54,7 +54,7 @@ def details() -> Iterable[Cell]:
     return sessions.details()
 
 
-@sessions_cli.command(help="Run a workflow fron an artifact to drive the current session forward.")
+@sessions_cli.command(help="Run a workflow from an artifact to drive the current session forward.")
 @cells_cli
 def run(workflow_id: FullArtifactIdArgument) -> Iterable[Cell]:
     return sessions.start_workflow(workflow_id)

donna/machine/primitives.py

@@ -20,7 +20,7 @@ if TYPE_CHECKING:
     from donna.workspaces.worlds.base import World
 
 
-# TODO: Currently is is a kind of God interface. It is convinient for now.
+# TODO: Currently it is a kind of God interface. It is convenient for now.
 #       However, in future we should move these methods into specific subclasses.
 class Primitive(BaseEntity):
     config_class: ClassVar[type[ArtifactSectionConfig]] = ArtifactSectionConfig

donna/machine/sessions.py

@@ -47,7 +47,7 @@ def _save_state(state: ConsistentState) -> Result[None, ErrorsList]:
 @unwrap_to_error
 def _state_run(mutator: MutableState) -> Result[None, ErrorsList]:
     while mutator.has_work():
-        mutator.exectute_next_work_unit().unwrap()
+        mutator.execute_next_work_unit().unwrap()
         _save_state(mutator.freeze()).unwrap()
 
     return Ok(None)

donna/machine/state.py

@@ -160,7 +160,7 @@ class MutableState(BaseState):
         self.apply_changes(changes)
 
     @unwrap_to_error
-    def exectute_next_work_unit(self) -> Result[None, ErrorsList]:
+    def execute_next_work_unit(self) -> Result[None, ErrorsList]:
         next_work_unit = self.get_next_work_unit()
         assert next_work_unit is not None
 
@@ -190,7 +190,7 @@ class StateNode(Node):
                 """
             The session is IDLE. There are no active tasks.
 
-            - If the developer asked you to start working on a new task, you can do so by initiating a new workflow.
+            - If the developer asked you to start working on a new task, you can do so by running a new workflow.
             - If you have been working on a task, consider it completed and REPORT THE RESULTS TO THE DEVELOPER.
                 """
             )