Filesystem-coupled artifact IDs; worlds removing

.agents/donna/intro.md → .agents/donna/intro.donna.md

@@ -21,7 +21,7 @@ We may need coding agents on the each step of the process, but there no reason f
 
 ## 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.
+To simplify searching for artifacts by their semantics, Donna allows tagging artifacts with semantically valuable keywords. The synced Donna artifacts addressed under `**` use the next set of tags.
 
 Artifact type tags:
 
@@ -30,7 +30,7 @@ Artifact type tags:
 
 ## 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.
+1. On start of the YOUR session you **MUST** read and understand instruction on using the Donna tool `{{ donna.lib.view("./usage/cli.donna.md") }}`. 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.
@@ -39,7 +39,7 @@ Artifact type tags:
 
 ## Journaling
 
-You MUST use `donna journal write` to track your actions and thoughts, according the description in `{{ donna.lib.view("donna:usage:cli") }}`.
+You MUST use `donna journal write` to track your actions and thoughts, according the description in `{{ donna.lib.view("./usage/cli.donna.md") }}`.
 
 Journaling is a required part of workflow execution. An action request MUST be considered incomplete until required journal records are written.
 

.agents/donna/research/specs/report.md → .agents/donna/research/specs/report.donna.md

@@ -4,19 +4,19 @@
 kind = "donna.lib.specification"
 ```
 
-This document describes the format and structure of a Research Report document used by Donna workflows from `donna:research:*` namespace.
+This document describes the format and structure of a Research Report document used by Donna workflows from `../**` 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.
+Donna introduces a group of workflows located in `../**` 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.
+Session-related research artifacts MUST be stored as `@/.donna/session/research/<short-problem-related-identifier>.donna.md`, 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:
+The research report is a Donna artifact (check `{{ donna.lib.view("../../usage/artifacts.donna.md") }}`) 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.
@@ -35,7 +35,7 @@ The research report is a Donna artifact (check `{{ donna.lib.view("donna:usage:a
 ## 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 `{{ donna.lib.view("../../usage/artifacts.donna.md") }}`.
 - You MUST follow the structure specified in this document.
 
 ### List format

donna/fixtures/specs/research/work/research.md → .agents/donna/research/work/research.donna.md

@@ -20,8 +20,8 @@ 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.
+1. Read the specification `{{ donna.lib.view("../../usage/artifacts.donna.md") }}` if you haven't done it yet.
+2. Read the specification `{{ donna.lib.view("../specs/report.donna.md") }}` if you haven't done it yet.
 3. `{{ donna.lib.goto("ensure_problem_description_exists") }}`
 
 ## Ensure problem description exists
@@ -34,7 +34,7 @@ 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") }}`.
+2. If you have no problem description in your context, but you know it is in one of `@/.donna/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
@@ -44,8 +44,8 @@ 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 #}
+1. Based on the problem description you have, suggest an artifact name in the format `@/.donna/session/research/<short-problem-related-identifier>.donna.md`. `<short-problem-related-identifier>` MUST be unique within the session.
+{# TODO: we can add donna.lib.list('@/.donna/session/**') here as the command to list all session artifacts #}
 2. Create the artifact and specify an original problem description in it.
 3. `{{ donna.lib.goto("formalize_research") }}`
 

donna/fixtures/specs/rfc/specs/design.md → .agents/donna/rfc/specs/design.donna.md

@@ -8,11 +8,11 @@ This document describes the format and structure of a Design document used to de
 
 ## 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.
+Donna introduces a group of workflows located in `../**` 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.
+If not otherwise specified, Design documents for the session MUST be stored as `@/.donna/session/design/<short-problem-related-identifier>.donna.md` artifacts under `<project-root>/.donna/session`.
 
 **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.
 
@@ -24,7 +24,7 @@ The Design document MUST NOT be a high-level description of the problem and solu
 
 ## Design document structure
 
-The RFC document is Donna artifact (check `{{ donna.lib.view("donna:usage:artifacts") }}`) with the next structure:
+The RFC document is Donna artifact (check `{{ donna.lib.view("../../usage/artifacts.donna.md") }}`) 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.
@@ -40,7 +40,7 @@ The RFC document is Donna artifact (check `{{ donna.lib.view("donna:usage:artifa
 ## 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 `{{ donna.lib.view("../../usage/artifacts.donna.md") }}`.
 - You MUST follow the structure specified in this document.
 
 ### List format

.agents/donna/rfc/specs/request_for_change.md → .agents/donna/rfc/specs/request_for_change.donna.md

@@ -4,19 +4,19 @@
 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 is an input for a Design document creation.
+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 `../**` 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 and Design documents.
+Donna introduces a group of workflows located in `../**` 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.
+If not otherwise specified, RFC documents for the session MUST be stored as `@/.donna/session/rfc/<short-problem-related-identifier>.donna.md` artifacts under `<project-root>/.donna/session`.
 
 ## RFC structure
 
-The RFC document is Donna artifact (check `{{ donna.lib.view("donna:usage:artifacts") }}`) with the next structure:
+The RFC document is Donna artifact (check `{{ donna.lib.view("../../usage/artifacts.donna.md") }}`) 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.
@@ -34,7 +34,7 @@ The RFC document is Donna artifact (check `{{ donna.lib.view("donna:usage:artifa
 ## 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 `{{ donna.lib.view("../../usage/artifacts.donna.md") }}`.
 - You MUST follow the structure specified in this document.
 
 ### List format
@@ -136,7 +136,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 the specification project:specs:abc`
+- Good: `- The solution MUST follow the specification ../../../../specs/abc.donna.md`
 - Good: `MUST not change public CLI flags`
 
 ## `Requirements` section
@@ -216,7 +216,7 @@ 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: `- Inspect artifact `../../../../specs/authentication.donna.md`; 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
@@ -238,7 +238,7 @@ Examples:
 - Bad: `- Implement authentication code`
 - Bad: `- Refactor auth module.`
 - Good: `- Module app/auth/authentication.py exists.`
-- Good: `- Donna artifact project:specs:authentication exists.`
+- Good: `- Donna artifact ../../../../specs/authentication.donna.md exists.`
 - Good: `- Test suite tests/auth/ exists.`
 
 ## `Action items` section
@@ -259,7 +259,7 @@ 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: `- Create an artifact ../../../../specs/authentication.donna.md 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.`

donna/fixtures/specs/rfc/work/design.md → .agents/donna/rfc/work/design.donna.md

@@ -5,7 +5,7 @@ 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`.
+This workflow creates a Design document artifact based on an RFC and aligned with `../specs/design.donna.md`.
 
 ## Start Work
 
@@ -15,8 +15,8 @@ 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.
+1. Read the specification `{{ donna.lib.view("../specs/design.donna.md") }}` if you haven't done it yet.
+2. Read the specification `{{ donna.lib.view("../../usage/artifacts.donna.md") }}` if you haven't done it yet.
 3. `{{ donna.lib.goto("ensure_rfc_artifact_exists") }}`
 
 ## Ensure RFC artifact exists
@@ -29,7 +29,7 @@ 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") }}`.
+2. If you have no RFC artifact id in your context, but you know it is in one of `{{ donna.lib.list("@/.donna/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
@@ -39,7 +39,7 @@ 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.
+1. If the name of the artifact is not specified explicitly, assume it to be `@/.donna/session/design/<short-problem-related-identifier>.donna.md`, where `<short-problem-related-identifier>` SHOULD correspond to the RFC slug.
 2. Save the next template into the artifact, replace `<variables>` with appropriate values.
 
 ~~~
@@ -81,7 +81,7 @@ 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.
+1. Read the specification `{{ donna.lib.view("../specs/design.donna.md") }}` 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.
@@ -95,7 +95,7 @@ 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") }}`.
+1. List mismatches between the Design artifact and the Design specification `{{ donna.lib.view("../specs/design.donna.md") }}`.
 2. For each mismatch, make necessary edits to the Design draft artifact to ensure compliance.
 3. `{{ donna.lib.goto("review_design_content") }}`
 
@@ -106,7 +106,7 @@ 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.
+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("../../research/work/research.donna.md") }}` 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") }}`.

donna/fixtures/specs/rfc/work/do.md → .agents/donna/rfc/work/do.donna.md

@@ -76,7 +76,7 @@ kind = "donna.lib.request_action"
 
 1. Choose the workflow to plan the work. If you created a Design document in the previous step, use it as a basis.
 2. Run the chosen workflow.
-3. Ensure you know the workflow id created in the previous step (default is `session:execute_rfc` if not specified).
+3. Ensure you know the workflow id created in the previous step (default is `@/.donna/session/execute_rfc.donna.md` if not specified).
 4. After completing the workflow `{{ donna.lib.goto("execute_rfc_work") }}`.
 
 ## Execute RFC work
@@ -86,7 +86,7 @@ id = "execute_rfc_work"
 kind = "donna.lib.request_action"
 ```
 
-1. Run the workflow created by the plan step (default: `session:execute_rfc`) and complete it.
+1. Run the workflow created by the plan step (default: `@/.donna/session/execute_rfc.donna.md`) and complete it.
 2. After completing the workflow `{{ donna.lib.goto("polish_changes") }}`.
 
 ## Polish changes

donna/fixtures/specs/rfc/work/plan.md → .agents/donna/rfc/work/plan.donna.md

@@ -6,7 +6,7 @@ kind = "donna.lib.workflow"
 start_operation_id = "start"
 ```
 
-This workflow plans the work required to implement a specified Design document. The RFC document SHOULD be used as a helper context. The result of this workflow is a new workflow in the `session:*` world with detailed steps to implement the designed changes.
+This workflow plans the work required to implement a specified Design document. The RFC document SHOULD be used as a helper context. The result of this workflow is a new workflow stored as a `@/.donna/session/**` artifact under `<project-root>/.donna/session` with detailed steps to implement the designed changes.
 
 ## Start Work
 
@@ -18,7 +18,7 @@ fsm_mode = "start"
 
 1. Read the Design document that the developer or parent workflow wants you to implement.
 2. Read the RFC document that the developer or parent workflow wants you to implement, if it exists.
-3. Read the specification `{{ donna.lib.view("donna:usage:artifacts") }}` if you haven't done it yet.
+3. Read the specification `{{ donna.lib.view("../../usage/artifacts.donna.md") }}` if you haven't done it yet.
 4. `{{ donna.lib.goto("prepare_workflow_artifact") }}`
 
 ## Prepare workflow artifact
@@ -28,7 +28,7 @@ id = "prepare_workflow_artifact"
 kind = "donna.lib.request_action"
 ```
 
-1. If the name of the artifact is not specified explicitly, assume it to `session:plans:<short-id-equal-to-design-slug>`.
+1. If the name of the artifact is not specified explicitly, assume it to `@/.donna/session/plans/<short-id-equal-to-design-slug>.donna.md`.
 2. Create a workflow with the next operations:
    - Start
    - A step for each action point in the RFC document and each item in the `Order of implementation` in Design document with the goal to minimize dependencies between steps and introduce changes incrementally.