donna 0.2.0__py3-none-any.whl → 0.2.2__py3-none-any.whl

donna/artifacts/intro.md

@@ -0,0 +1,39 @@
+# Introduction to the Donna tool
+
+```toml donna
+kind = "donna.lib.specification"
+```
+This document provides an introduction to the Donna — a CLI tool that helps manage the work of AI agents like Codex.
+
+## Overview
+
+Donna is designed to to invert control flow: instead of agents deciding what to do next, the `donna` tells agents what to do next by following predefined workflows.
+
+The core idea is that most of high-level workflows are more algorithmic than it may seem at first glance. For example, it may be difficult to fix a particular type issue in the codebase, but the overall process of polishing the codebase is quite linear:
+
+1. Ensure all tests pass.
+2. Ensure the code is formatted correctly.
+3. Ensure there are no linting errors.
+4. Go to the step 1 if you changed something in the process.
+5. Finish.
+
+We may need coding agents on the each step of the process, but there no reason for agents to manage the whole grooming loop by themselves — it take longer time, spends tokens and may lead to confusion of agents.
+
+## Artifact 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:
+
+- `workflow` — workflow artifact — is set automatically by Donna.
+- `specification` — specification artifact — is set automatically by Donna.
+
+{# We recommend using those tags in `project:` and `session:` worlds as well to keep consistency. #}
+
+## Instructions
+
+1. On start of the YOUR session you **MUST** read and understand instruction on using the Donna tool `{{ donna.lib.view("donna:usage:cli") }}`. It **MUST** be a one time operation. Do not repeat it unless you forget how to use the tool.
+2. If you need to perform a work with Donna, you **MUST** select an appropriate Donna workflow to perform the work and run it.
+3. If there is no appropriate workflow, ask the developer for a precise instructions on what to do.
+4. List all workflows: `{{ donna.lib.list("**", tags=["workflow"]) }}`
+5. List all specifications: `{{ donna.lib.list("**", tags=["specification"]) }}`

donna/artifacts/research/specs/report.md

@@ -0,0 +1,163 @@
+# Format of the Research Report document
+
+```toml donna
+kind = "donna.lib.specification"
+```
+
+This document describes the format and structure of a Research Report document used by Donna workflows from `donna:research:*` namespace.
+
+## Overview
+
+Donna introduces a group of workflows located in `donna:research:*` namespace that organize the process of researching a problem, collecting information, analyzing it, synthesizing options, and producing a final solution.
+
+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.
+
+The agent (via workflows) creates the artifact and updates it iteratively as the research process progresses.
+
+## Research report structure
+
+The research report is a Donna artifact (check `{{ donna.lib.view("donna:usage:artifacts") }}`) with the next structure:
+
+- **Primary section** -- title and short description of the research problem.
+- **Original problem description** -- original problem statement from the developer or parent workflow.
+- **Formalized problem description** -- formalized version of the problem statement.
+- **Goals** -- list of goals the research should achieve.
+- **Desired form of final solution** -- description of the expected form and constraints for the final solution.
+- **Solution space** -- description of analysis axes and synthesis dimensions.
+- **Information to collect** -- list of information required to research the problem.
+- **Information sources** -- list of sources that can provide the required information.
+- **Collected information** -- gathered information with source references.
+- **Analysis** -- analysis of collected information along the specified axes.
+- **Synthesized solutions** -- synthesized solution options along the specified dimensions.
+- **Evaluation** -- evaluation of synthesized solutions against the goals.
+- **Final solution** -- final solution in the desired form.
+
+## 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 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 a single focus.
+- Transform an abstract item into a concrete one by referencing specific artifacts, measurable criteria, verifiable conditions, etc.
+
+### Trusted inputs
+
+Some sections of the research report MUST be based on trusted inputs. Trusted inputs are:
+
+- 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 they describe constraints or best practices.
+- Primary research sources (datasets, reports, official publications) were used to collect the required information.
+
+## `Primary` section
+
+- Title MUST be concise and reflect the essence of the research problem.
+- Description MUST provide a brief overview of the problem, its purpose, and why research is needed.
+
+## `Original problem description` section
+
+- This section MUST contain the original problem description from the developer or from the parent workflow.
+- The problem description MUST NOT be modified by agents.
+
+## `Formalized problem description` section
+
+- The section MUST contain a clear professional high-level description of the problem based on the original description.
+- The section MUST be limited to a single paragraph with a few sentences.
+- The section MUST explain what someone gains after the problem is solved and how they can see it working.
+
+## `Goals` section
+
+- This section MUST contain a list of goals that the research should achieve.
+- Each goal MUST be grounded in the formalized problem description.
+
+Goal quality criteria:
+
+- 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:
+
+- Bad: `- Investigate database options.`
+- Good: `- Identify a database option that meets the project's scalability requirements.`
+
+## `Desired form of final solution` section
+
+- The section MUST be grounded in the formalized problem description and the goals.
+- The section MUST describe the expected form of the final solution (for example: recommendation, decision matrix, implementation plan, or specification).
+- The section MUST specify any required structure, formatting, or constraints on the final solution.
+- The section SHOULD be a short list or a short paragraph, whichever is clearer for the problem.
+
+## `Solution space` section
+
+- The section MUST describe the axes along which collected information will be analyzed and the dimensions along which solutions will be synthesized.
+- The section MUST contain two subsections: **Analysis axes** and **Synthesis dimensions**.
+- Each axis or dimension MUST be grounded in the goals or the formalized problem description.
+
+### `Analysis axes` subsection
+
+- The subsection MUST contain a list of analysis axes.
+- Each axis MUST describe a single perspective or criterion used to analyze information.
+- Each axis SHOULD be phrased so it is clear how to apply it to collected information.
+
+### `Synthesis dimensions` subsection
+
+- The subsection MUST contain a list of synthesis dimensions.
+- Each dimension MUST describe a single perspective or criterion used to synthesize solution options.
+- Each dimension SHOULD make the comparison between options easier.
+
+## `Information to collect` section
+
+- The section MUST contain a list of information items required to research the problem.
+- Each item MUST be specific enough to be collected or verified from sources.
+- Each item MUST be grounded in the formalized problem description or the goals.
+
+## `Information sources` section
+
+- The section MUST contain a list of sources that can provide the required information.
+- Each source entry MUST include a short identifier and a brief description of the source.
+- Each source entry SHOULD include access method, scope, and reliability notes if relevant.
+- Each source MUST be relevant to at least one item from **Information to collect**.
+
+## `Collected information` section
+
+- The section MUST contain the collected information mapped to the items from **Information to collect**.
+- Each collected information item MUST reference one or more source identifiers from **Information sources**.
+- The section MUST make it clear which information items are satisfied and which are missing.
+- If a required information item cannot be collected, the section MUST state that explicitly and explain why.
+
+## `Analysis` section
+
+- The section MUST analyze the collected information along the **Analysis axes**.
+- The analysis MUST be organized so each axis can be reviewed independently.
+- The analysis MUST clearly separate observed facts from inferences or assumptions.
+- The analysis format MUST fit the **Desired form of final solution** and should make downstream synthesis straightforward.
+
+## `Synthesized solutions` section
+
+- The section MUST present synthesized solutions or options in a format consistent with the **Synthesis dimensions**.
+- Each solution SHOULD reference the analysis items that justify it.
+- The synthesis format MUST fit the **Desired form of final solution**.
+
+## `Evaluation` section
+
+- The section MUST evaluate each synthesized solution against the **Goals**.
+- The evaluation MUST make trade-offs explicit and identify risks or uncertainties.
+- The evaluation MUST result in a clear comparison between solutions.
+
+## `Final solution` section
+
+- The section MUST present the final solution in the form specified in **Desired form of final solution**.
+- The final solution MUST be justified by the evaluation results.
+- If the evaluation does not allow a confident final solution, the section MUST state the remaining uncertainties and what additional information would resolve them.

donna/artifacts/research/work/research.md

@@ -0,0 +1,198 @@
+# Research workflow
+
+```toml donna
+kind = "donna.lib.workflow"
+start_operation_id = "start"
+```
+
+Workflow for performing research on a given question/problem/situation. Collects relevant information, analyzes it, synthesizes possible options, and produces an answer/solution/deliverables.
+
+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 conduct research.
+- When other workflows need to perform research as a subtask.
+
+## Start
+
+```toml donna
+id = "start"
+kind = "donna.lib.request_action"
+fsm_mode = "start"
+```
+
+1. Read the specification `{{ donna.lib.view("donna:usage:artifacts") }}` if you haven't done it yet.
+2. Read the specification `{{ donna.lib.view("donna:research:specs:report") }}` if you haven't done it yet.
+3. `{{ donna.lib.goto("ensure_problem_description_exists") }}`
+
+## Ensure problem description exists
+
+```toml donna
+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.
+
+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") }}`.
+3. If you have no problem description in your context, and you don't know where it is, ask the developer to provide it. After you get the problem description, `{{ donna.lib.goto("prepare_artifact") }}`.
+
+## Prepare research artifact
+
+```toml donna
+id = "prepare_artifact"
+kind = "donna.lib.request_action"
+```
+
+1. Based on the problem description you have, suggest an artifact name in the format `session:research:<short-problem-related-identifier>`. `<short-problem-related-identifier>` MUST be unique within the session.
+{# TODO: we can add donna.lib.list('session:*') here as the command to list all artifacts in session #}
+2. Create the artifact and specify an original problem description in it.
+3. `{{ donna.lib.goto("formalize_research") }}`
+
+## Formalize Research
+
+```toml donna
+id = "formalize_research"
+kind = "donna.lib.request_action"
+```
+
+1. Using your knowledge about the project and the original problem description, formulate a format description of the problem
+2. Update the artifact with the formalized problem description.
+3. `{{ donna.lib.goto("set_primary_section_of_the_research_artifact") }}`
+
+## Set primary section of the research artifact
+
+```toml donna
+id = "set_primary_section_of_the_research_artifact"
+kind = "donna.lib.request_action"
+```
+
+1. Based on the formalized problem description, update the primary (h1) section of the research artifact to reflect the problem being researched. So the agents can effectively find and understand the research artifact using Donna.
+2. `{{ donna.lib.goto("formulate_goals") }}`
+
+## Formulate Goals
+
+```toml donna
+id = "formulate_goals"
+kind = "donna.lib.request_action"
+```
+
+1. Based on the formalized problem description, formulate a list of goals that the problem solution should achieve.
+2. Update the artifact with the list of goals.
+3. `{{ donna.lib.goto("fomalize_form_of_final_solution") }}`
+
+## Formalize form of final solution
+
+```toml donna
+id = "fomalize_form_of_final_solution"
+kind = "donna.lib.request_action"
+```
+
+1. Based on the formalized problem description and the list of goals, formulate the desired form of the final solution.
+2. Update the artifact with the desired form of the final solution.
+3. `{{ donna.lib.goto("describe_solution_space") }}`
+
+## Describe solution space
+
+```toml donna
+id = "describe_solution_space"
+kind = "donna.lib.request_action"
+```
+
+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.
+
+1. List the analysis axes.
+2. List the synthesis dimensions.
+3. Update the artifact with the description of the solution space.
+4. `{{ donna.lib.goto("describe_information_to_collect") }}`
+
+## Describe information to collect
+
+```toml donna
+id = "describe_information_to_collect"
+kind = "donna.lib.request_action"
+```
+
+1. Based on the formalized problem description and the list of goals, list the information to be collected to research the problem.
+2. Update the artifact with the description of the information to collect.
+3. `{{ donna.lib.goto("list_information_sources") }}`
+
+## List information sources
+
+```toml donna
+id = "list_information_sources"
+kind = "donna.lib.request_action"
+```
+
+1. Based on the formalized problem description and the list of goals, formulate a list of information sources that can help to research the problem.
+2. Update the artifact with the list of information sources.
+3. `{{ donna.lib.goto("collect_information") }}`
+
+## Collect information
+
+```toml donna
+id = "collect_information"
+kind = "donna.lib.request_action"
+```
+
+1. For each information source from the list:
+   1. For each piece of required information from the description:
+      1. If the source can not provide this piece of information, skip it.
+      2. Access the source and collect the required information.
+      3. Update the artifact with the collected information.
+2. `{{ donna.lib.goto("analyze_information") }}`
+
+## Analyze information
+
+```toml donna
+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 required solution form.
+2. Update the artifact with the analysis results.
+3. `{{ donna.lib.goto("synthesize_solutions") }}`
+
+## Synthesize solutions
+
+```toml donna
+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 required solution form.
+2. Update the artifact with the synthesized solutions.
+3. `{{ donna.lib.goto("evaluate_solutions") }}`
+
+## Evaluate solutions
+
+```toml donna
+id = "evaluate_solutions"
+kind = "donna.lib.request_action"
+```
+
+1. Evaluate the synthesized solutions against the goals from the formalized problem description.
+2. Update the artifact with the evaluation results.
+3. `{{ donna.lib.goto("produce_final_solution") }}`
+
+## Produce final solution
+
+```toml donna
+id = "produce_final_solution"
+kind = "donna.lib.request_action"
+```
+
+1. Based on the evaluation results, produce the final solution in the desired form.
+2. Update the artifact with the final solution.
+3. `{{ donna.lib.goto("finish") }}`
+
+## Finish
+
+```toml donna
+id = "finish"
+kind = "donna.lib.finish"
+```
+
+Research workflow completed. Provide the final research output to the developer.

donna/artifacts/rfc/specs/request_for_change.md

@@ -0,0 +1,270 @@
+# Format of the Request for Change document
+
+```toml donna
+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.
+
+## 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.
+
+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:
+
+- **Primary section** — title and short description of the proposed change.
+- **Original description** — original description of the requested changes from the developer or parent workflow.
+- **Formal description** — formal description of the requested changes.
+- **Goals** — list of goals that the proposed change aims to achieve.
+- **Objectives** — list of objectives that need to be accomplished to achieve the goals.
+- **Constraints** — list of constraints that must be considered while implementing the proposed change.
+- **Requirements** — list of requirements that the proposed change must fulfill.
+- **Acceptance criteria** — list of criteria that define when the proposed change is considered complete and successful.
+- **Solution** — list of statements about how the final result should look like.
+- **Verification** — list of statements about how to verify each objective, constraint, requirement, and acceptance criterion.
+- **Deliverables** — list of deliverables that should be produced as part of the proposed change.
+- **Action items** — unordered list of atomic actions/changes that must be performed to implement the proposed change.
+
+## 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: `- 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 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 a single focus.
+- Transform an abstract item into a concrete one by specifying measurable criteria or user-visible behavior.
+
+### Trusted inputs
+
+Some sections of the RFC document MUST be based on trusted inputs. Trusted inputs are:
+
+- 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 they describe constraints or best practices.
+
+## `Primary` section
+
+- Title MUST be concise and reflect the essence of the proposed change.
+- Description MUST provide a brief overview of the proposed change, its purpose, and its expected impact.
+
+## `Original description` section
+
+- This section MUST contain the original request from the developer or from the parent workflow.
+- The request MUST NOT be modified by agents.
+
+## `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 be limited to a single paragraph with a few sentences.
+- 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
+
+- This section MUST contain a list of goals that the proposed change aims to achieve.
+
+The goal quality criteria:
+
+- 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:
+
+- Bad: `- Implement authentication system.`
+- Good: `- Protect user data from unauthorized access.`
+
+## `Objectives` section
+
+- The section MUST contain a list of objectives that need to be completed to achieve the goals.
+- Each goal MUST have a set of objectives that, when all achieved, ensure the goal is met.
+- Each goal MUST have 2–6 objectives, unless the goal is demonstrably trivial (≤1 artifact, no dependencies).
+
+Objective quality criteria:
+
+- An objective MUST be a specific, measurable condition that must be true for a goal to be satisfied.
+- An objective MUST describe an achieved state, capability, artifact, or behavior.
+
+Examples:
+
+- Bad: `- Create user authentication and authorization system.`
+- Bad: `- Design user authentication flow.`
+- Good: `- Specification for user authentication flow exists.`
+- Good: `- User is able to log in using email and password.`
+
+## `Constraints` section
+
+- The section MUST contain a list of constraints that the changes MUST respect.
+- The section MAY be empty only if no constraints are explicitly known.
+- A constraint MUST be derived from trusted inputs. Agents MUST NOT invent constraints.
+
+Constraint quality criteria:
+
+- A constraint MUST be a hard limit on the solution space.
+- A constraint MUST be externally imposed by technology, policy, compatibility, time, budget, etc.
+- A constraint MUST NOT describe desired behavior or outcomes.
+- A constraint MUST be non-negotiable within the scope of the RFC.
+
+Examples:
+
+- Bad: `- The system should be easy to maintain.`
+- 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 the specification project:specs:abc`
+- Good: `MUST not change public CLI flags`
+
+## `Requirements` section
+
+- The section MUST contain a list of requirements that the proposed change MUST fulfill.
+
+Requirement quality criteria:
+
+- A requirement MUST be a single atomic condition, capability, or feature that the system MUST meet, provide, or exhibit after the change is implemented.
+- A requirement MUST be directly testable.
+- A requirement MUST be stated independently of implementation details.
+- A requirement MUST NOT restate goals or objectives verbatim.
+
+Examples:
+
+- Bad: `- Improve security.`
+- Bad: `- Implement OAuth.`
+- Good: `- The system MUST reject authentication attempts with invalid credentials.`
+- Good: `- The system MUST log all failed authentication attempts with timestamp and user identifier.`
+
+## `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 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: 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:
+
+- Bad: `- All requirements are implemented.`
+- Bad: `- The feature works as expected.`
+- Good: `- The artifact with documentation for X exists.`
+- Good: `- The autotest for requirement Y exists.`
+- Good: `- All autotests pass without errors.`
+- Good: `- The tool can run on Python 3.12 without errors.`
+
+## `Solution` section
+
+- The section MUST contain a list of statements describing how the system should look like/behave after the proposed changes are implemented.
+- The section MUST NOT establish an order of implementation steps.
+- The full solution MUST ensure the truth/validity of all statements in the RFC.
+
+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 the present tense, describing an achieved state.
+
+Examples:
+
+- Bad: `- First implement the database schema, then add API endpoints.`
+- Bad: `- Use framework X to handle authentication.`
+- Good: `- The system exposes an authentication API that accepts credentials and returns an access token on success.`
+- Good: `- User-facing documentation describes how to configure and use the authentication feature.`
+
+## `Verification` section
+
+- The section MUST contain a list of checks that MUST be passed to prove that the work is complete and correct.
+- Each verification statement MUST map to a single item from **Objectives**, **Constraints**, **Requirements**, or **Acceptance criteria**.
+- Each **Objective**, **Constraint**, **Requirement**, or **Acceptance criterion** MUST map to a single verification statement.
+- Each verification statement MUST describe *how* the corresponding item can be verified.
+
+Verification quality criteria:
+
+- A verification statement MUST be a concrete verification step or check.
+- A verification statement MUST be automatable if it is possible.
+- A verification statement SHOULD be verifiable by agents without human intervention.
+- A verification statement MUST result in a boolean outcome (verified / not verified).
+- A verification statement MUST reference specific artifacts, commands, tests, or observable behavior.
+
+Examples:
+
+- Bad: `- Verify that authentication works correctly.`
+- Bad: `- Review the implementation manually.`
+- Good: `- Run test suite `tests/auth/test_login.py`; all tests MUST pass.`
+- Good: `- Inspect artifact `project:specs:authenticationd`; it MUST exist and contain section "Login flow".`
+- Good: `- Execute CLI command `tool login` with invalid credentials; command MUST exit with non-zero code.`
+
+## `Deliverables` section
+
+- The section MUST contain a list of concrete artifacts that MUST exist after the changes are implemented.
+- A deliverable MUST be derived from trusted inputs. Agents MUST NOT invent deliverables.
+
+Deliverable quality criteria:
+
+- 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.
+- Explicitly add source files as deliverables only when the task is specifically
+  about creating or modifying those files (e.g., "MUST add docs/cli.md …").
+
+Examples:
+
+- Bad: `- Implement authentication code`
+- Bad: `- Refactor auth module.`
+- Good: `- Module app/auth/authentication.py exists.`
+- Good: `- Donna artifact project:specs:authentication exists.`
+- Good: `- Test suite tests/auth/ exists.`
+
+## `Action items` section
+
+- The section MUST contain an unordered list of atomic actions.
+
+Action item quality criteria:
+
+- An action item MUST be a single change that can be applied or executed.
+- An action item MUST be small enough to be completed without further decomposition.
+- An action item MUST be phrased as an imperative sentence.
+- An action item MUST affect a specific artifact, file, config, etc.
+- An action item MUST reference concrete paths, identifiers, or commands.
+- An action item MUST be actionable by an agent.
+
+Examples:
+
+- Bad: `- Work on authentication.`
+- Bad: `- Improve security everywhere.`
+- Bad: `- Fix the bugs A`
+- Good: `- Create an artifact project:specs:authentication with sections "Login flow" and "Token lifecycle".`
+- Good: `- Add test file tests/auth/test_login.py covering invalid credential cases.`
+- Good: `- Implement test tests/auth/test_login.py:TestLogin:test_invalid_credentials.`
+- Good: `- Update CLI help text to include login command description.`
+- Good: `- Implement function app/auth/authentication.py:authenticate_user().`