Removed the donna.workspaces.worlds.python world

donna/artifacts/usage/worlds.md → .agents/donna/usage/worlds.md

@@ -21,7 +21,7 @@ s3 buckets, git repositories, databases, etc.
 
 Default worlds and there locations are:
 
-- `donna` — `donna.artifacts` — the subpackage with artifacts provided by Donna itself.
+- `donna` — `<project-root>/.agents/donna` — the project-local bundled Donna specs installed from `donna/fixtures/specs` by workspace init/update.
 - `home` — `~/.donna/home` — the user-level donna artifacts, i.e. those that should be visible for all workspaces on this machine.
 - `project` — `<project-root>/.donna/project` — the project-level donna artifacts, i.e. those that are specific to this project.
 - `session` — `<project-root>/.donna/session` — the session world that contains the current state of work performed by Donna.

.donna/project/core/top_level_architecture.md

@@ -26,7 +26,8 @@ The code is separated by layers/subsystems into subpackages:
 - `donna.cli` — code that implements the `donna` CLI tool, its commands, arguments parsing, etc.
 - `donna.primitives` — code that implements basic building blocks for Donna's behavior: concrete implementations of various classes from the `donna.machine`.
 - `donna.lib` — module that contains constructed primitives to be used in donna artifacts by referencing them by python import path. Like `donna.lib.workflow`, `donna.lib.goto`, etc.
-- `donna.artifacts` — artifacts that are distributed with Donna itself: specifications of how it works, predefined workflows, etc.
+- `donna.fixtures.skills` — bundled skills that are distributed with Donna and synced into project workspaces under `.agents/skills`.
+- `donna.fixtures.specs` — bundled Donna specifications and workflows that are distributed with Donna and synced into project workspaces under `.agents/donna`.
 
 ## Data structures
 

changes/unreleased.md

@@ -1,10 +1,14 @@
 ### Migration
 
+- Run `donna workspaces update` in existing projects so bundled Donna specs are installed into `.agents/donna` for the new filesystem-backed `donna` world.
 - Update your scripts and specs to use external tools or direct file edits to create, update, move, copy, or delete world artifacts instead using removed Donna commands.
 
 ### Changes
 
 - `--tag` option is replaced with `--predicate` in all CLI commands that accept artifact patterns.
+- Removed the Python donna world.
+  - Added workspace spec dumping into `.agents/donna` on `donna workspaces init` and `donna workspaces update`.
+  - Reconfigured the default `donna` world to load bundled specs from `.agents/donna` through the filesystem world and removed the Python world implementation.
 - Removed world artifact mutation support.
   - Removed `donna artifacts` mutation commands and the supporting artifact-mutation code paths.
   - Removed `readonly` world-artifact mutability modeling from workspace config and world abstractions.
@@ -13,5 +17,10 @@
 
 ### Breaking Changes
 
+- Donna no longer exposes bundled specs through the Python-backed `donna` world; `donna workspaces init|update` now sync them into `.agents/donna`.
 - `donna artifacts` no longer supports `update`, `copy`, `move`, or `remove`.
 - Donna no longer mutates world artifacts through workspace APIs or world configuration.
+
+### Removals
+
+- Removed the Python world implementation and the `donna.artifacts` package-backed source of bundled Donna specs.

donna/__init__.py

@@ -1 +0,0 @@
-donna_artifacts_root = "donna.artifacts"

donna/cli/commands/workspaces.py

@@ -4,7 +4,7 @@
 import typer
 
 from donna.cli.application import app
-from donna.cli.types import SkillsOption
+from donna.cli.types import SkillsOption, SpecsOption
 from donna.cli.utils import cells_cli
 from donna.protocol.cell_shortcuts import operation_succeeded
 from donna.protocol.cells import Cell
@@ -23,20 +23,20 @@ def _resolve_target_dir() -> pathlib.Path:
 
 @workspaces_cli.command(help="Initialize Donna workspace.")
 @cells_cli
-def init(skills: SkillsOption = True) -> Iterable[Cell]:
+def init(skills: SkillsOption = True, specs: SpecsOption = True) -> Iterable[Cell]:
     target_dir = _resolve_target_dir()
 
-    initialize_workspace(target_dir, install_skills=skills).unwrap()
+    initialize_workspace(target_dir, install_skills=skills, install_specs=specs).unwrap()
 
     return [operation_succeeded("Workspace initialized successfully")]
 
 
 @workspaces_cli.command(help="Update Donna workspace files.")
 @cells_cli
-def update(skills: SkillsOption = True) -> Iterable[Cell]:
+def update(skills: SkillsOption = True, specs: SpecsOption = True) -> Iterable[Cell]:
     target_dir = _resolve_target_dir()
 
-    update_workspace(target_dir, install_skills=skills).unwrap()
+    update_workspace(target_dir, install_skills=skills, install_specs=specs).unwrap()
 
     return [operation_succeeded("Workspace updated successfully")]
 

donna/cli/types.py

@@ -168,6 +168,14 @@ def _parse_input_path(value: str) -> pathlib.Path:
     ),
 ]
 
+SpecsOption = Annotated[
+    bool,
+    typer.Option(
+        "--specs/--no-specs",
+        help="Enable or disable Donna specs updates in `.agents/donna`.",
+    ),
+]
+
 
 InputPathArgument = Annotated[
     pathlib.Path,

donna/fixtures/specs/intro.md

@@ -0,0 +1,59 @@
+# 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.
+
+## 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. 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("**", predicate='"workflow" in section.tags') }}`
+6. Run to list all specifications: `{{ donna.lib.list("**", predicate='"specification" in section.tags') }}`
+
+## 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/fixtures/specs/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.