Filesystem-coupled artifact IDs; worlds removing#72
Merged
Conversation
There was a problem hiding this comment.
Pull request overview
This PR removes the “worlds” abstraction and migrates Donna to filesystem-coupled artifact identifiers (project-relative @/... paths), along with new workspace file filtering and updated docs/specs to match the new artifact model.
Changes:
- Replaced colon-delimited artifact ids (
world:artifact[:section]) with filesystem-based ids (@/path/to/file.donna.md[:section]) across the runtime, CLI, directives, and docs. - Removed world implementations/configuration and replaced session world state/journal persistence with a dedicated
.donna/sessionfilesystem module. - Introduced artifact discovery via filesystem walking + configurable
file_filters, and updated bundled specs/workflows/skills to use the new paths.
Reviewed changes
Copilot reviewed 82 out of 85 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| specs/work/polish.donna.md | Adds a “polishing” workflow artifact using the new .donna.md format and section ids. |
| specs/work/log_changes.donna.md | Updates scoped session artifact references to @/.donna/session/**. |
| specs/intro.donna.md | Updates terminology/docs to filesystem-backed artifacts and @/... ids. |
| specs/core/top_level_architecture.donna.md | Updates architecture doc to reflect workspace/filesystem integration changes. |
| specs/core/error_handling.donna.md | Updates error handling examples to use context().artifacts.load(..., RENDER_CONTEXT_VIEW). |
| README.md | Updates public documentation to reflect filesystem artifact ids, new discovery/filtering, and new doc locations under .agents/donna. |
| donna/workspaces/worlds/filesystem.py | Removes filesystem world implementation (world model deprecated). |
| donna/workspaces/worlds/base.py | Removes world base abstractions (World, RawArtifact, constructors). |
| donna/workspaces/utils.py | Removes session_world() helper (replaced by workspace session filesystem utilities). |
| donna/workspaces/templates.py | Switches template rendering to use filesystem ArtifactId rather than FullArtifactId. |
| donna/workspaces/sources/markdown.py | Migrates markdown source config to single .donna.md extension and new id/path types. |
| donna/workspaces/sources/base.py | Replaces supported_extensions list with single extension and updates type signatures. |
| donna/workspaces/sessions.py | Adds filesystem-backed session directory/state/journal helpers. |
| donna/workspaces/markdown.py | Updates markdown parsing to use new ArtifactId type. |
| donna/workspaces/initialization.py | Updates workspace init to ensure session directory via workspaces.sessions. |
| donna/workspaces/errors.py | Removes world-specific error types/fields and updates artifact error messaging. |
| donna/workspaces/config.py | Removes world configs; adds file_filters + new SourceConfig with extension. |
| donna/workspaces/artifacts.py | Implements artifact discovery/loading from filesystem + filter evaluation + source dispatch. |
| donna/workspaces/artifacts_discovery.py | Removes world-based artifact discovery logic. |
| donna/protocol/formatters/llm.py | Adjusts cell formatting to preserve trailing newline separation. |
| donna/protocol/formatters/human.py | Adjusts cell formatting to add extra blank lines for readability. |
| donna/primitives/operations/run_script.py | Updates operation ids/types to ArtifactId + SectionId and new full-id composition. |
| donna/primitives/operations/request_action.py | Updates transition extraction/ids to SectionId and new artifact id types. |
| donna/primitives/operations/output.py | Updates next-operation ids to SectionId and new full-id composition. |
| donna/primitives/operations/finish_workflow.py | Updates meta construction signature to accept ArtifactId. |
| donna/primitives/directives/view.py | Updates directive argument parsing to normalize filesystem ids/patterns and use ArtifactIdPattern. |
| donna/primitives/directives/list.py | Updates directive argument parsing to normalize filesystem ids/patterns and use ArtifactIdPattern. |
| donna/primitives/directives/goto.py | Updates goto directive to build filesystem ArtifactSectionId-style ids. |
| donna/primitives/artifacts/workflow.py | Migrates workflow primitive to SectionId start ids and filesystem artifact id types. |
| donna/machine/tasks.py | Migrates task/work-unit identifiers to filesystem section ids and new internal id module. |
| donna/machine/state.py | Migrates state transitions to filesystem ArtifactSectionId and new internal id module. |
| donna/machine/sessions.py | Updates session lifecycle to reset .donna/session via workspace session helpers; uses filesystem ids. |
| donna/machine/primitives.py | Migrates primitive resolution to PythonPath and section ids to SectionId; removes construct_world. |
| donna/machine/operations.py | Migrates operation meta transition id type from old section id to SectionId. |
| donna/machine/journal.py | Switches journal persistence to filesystem session journal helpers; updates id types. |
| donna/machine/errors.py | Updates error models to filesystem ArtifactId/ArtifactSectionId and new internal ids. |
| donna/machine/changes.py | Updates change objects to use filesystem section ids and new internal ids. |
| donna/machine/artifacts.py | Migrates artifact/section models to filesystem ArtifactId, SectionId, and PythonPath. |
| donna/machine/action_requests.py | Migrates stored operation ids on action requests to filesystem ArtifactSectionId. |
| donna/lib/worlds.py | Removes default world constructor exports (world model removed). |
| donna/fixtures/specs/usage/worlds.md | Removes legacy worlds-based usage spec. |
| donna/fixtures/specs/usage/worlds.donna.md | Adds new filesystem layout usage spec describing artifact areas + file_filters. |
| donna/fixtures/specs/usage/cli.donna.md | Updates CLI usage spec to filesystem artifact ids/pattern semantics and file filter notes. |
| donna/fixtures/specs/usage/artifacts.donna.md | Updates artifact definition and internal links to new relative-path view() usage. |
| donna/fixtures/specs/rfc/work/request.donna.md | Updates RFC workflow to new session artifact paths and relative view() references. |
| donna/fixtures/specs/rfc/work/plan.donna.md | Updates plan workflow to create session workflows under @/.donna/session/**. |
| donna/fixtures/specs/rfc/work/do.donna.md | Updates meta workflow to reference new default session workflow paths. |
| donna/fixtures/specs/rfc/work/design.donna.md | Updates design workflow references to new relative view() usage. |
| donna/fixtures/specs/rfc/specs/request_for_change.donna.md | Updates RFC spec text/examples to filesystem artifact paths. |
| donna/fixtures/specs/rfc/specs/design.donna.md | Updates design spec text/examples to filesystem artifact paths. |
| donna/fixtures/specs/research/work/research.donna.md | Updates research workflow session artifact paths and relative view() references. |
| donna/fixtures/specs/research/specs/report.donna.md | Updates research report spec text/examples to filesystem artifact paths. |
| donna/fixtures/specs/intro.donna.md | Updates intro spec links and wording away from donna:* world ids. |
| donna/fixtures/skills/donna-start/SKILL.md | Updates startup skill to view **/intro.donna.md rather than legacy *:intro. |
| donna/fixtures/skills/donna-do/SKILL.md | Updates workflow-driving skill to view **/intro.donna.md rather than legacy *:intro. |
| donna/domain/python_path.py | Introduces PythonPath as an IdPath for dotted python identifiers. |
| donna/domain/internal_ids.py | Splits internal ids (TaskId/WorkUnitId/ActionRequestId) out of domain.ids. |
| donna/domain/ids.py | Simplifies identifier handling; moves path/pattern/internal id logic out; defines SectionId. |
| donna/domain/id_paths.py | Adds generalized IdPath + glob-capable IdPathPattern implementation. |
| donna/domain/artifact_ids.py | Introduces filesystem-based ArtifactId, ArtifactIdPattern, ArtifactSectionId, and normalization helpers. |
| donna/context/state.py | Switches state storage to filesystem session helpers. |
| donna/context/primitives.py | Migrates primitive cache keys/types to PythonPath. |
| donna/context/context.py | Migrates current operation id tracking to filesystem ArtifactSectionId. |
| donna/context/artifacts.py | Switches artifact cache to filesystem ids and filesystem loader/discovery functions. |
| donna/cli/types.py | Updates CLI parsing/validation to filesystem ids/patterns and supported extension checking. |
| donna/cli/commands/sessions.py | Updates sessions run / action-request-completed to filesystem ids and adds extension validation. |
| donna/cli/commands/artifacts.py | Updates artifact commands to filesystem patterns and adds extension validation. |
| changes/unreleased.md | Updates release notes for filesystem ids + file_filters (but contains outdated examples/wording). |
| bin/donna.sh | Switches to poetry -P <root> invocation rather than cd then poetry run. |
| .agents/skills/donna-start/SKILL.md | Syncs updated startup skill instructions to workspace copy. |
| .agents/skills/donna-do/SKILL.md | Syncs updated “do” skill instructions to workspace copy. |
| .agents/donna/usage/worlds.md | Removes legacy worlds-based usage spec from synced workspace copy. |
| .agents/donna/usage/worlds.donna.md | Adds synced filesystem layout usage spec to workspace copy. |
| .agents/donna/usage/cli.donna.md | Syncs updated CLI usage spec to workspace copy. |
| .agents/donna/usage/artifacts.donna.md | Syncs updated artifacts usage spec to workspace copy. |
| .agents/donna/rfc/work/request.donna.md | Syncs updated RFC request workflow to workspace copy. |
| .agents/donna/rfc/work/plan.donna.md | Syncs updated RFC plan workflow to workspace copy. |
| .agents/donna/rfc/work/do.donna.md | Syncs updated RFC do workflow to workspace copy. |
| .agents/donna/rfc/work/design.donna.md | Syncs updated RFC design workflow to workspace copy. |
| .agents/donna/rfc/specs/request_for_change.donna.md | Syncs updated RFC spec to workspace copy. |
| .agents/donna/rfc/specs/design.donna.md | Syncs updated design spec to workspace copy. |
| .agents/donna/research/work/research.donna.md | Syncs updated research workflow to workspace copy. |
| .agents/donna/research/specs/report.donna.md | Syncs updated research report spec to workspace copy. |
| .agents/donna/intro.donna.md | Syncs updated intro spec to workspace copy. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
33
to
37
| artifact_id = context["artifact_id"] | ||
|
|
||
| next_operation_id = artifact_id.to_full_local(argv[0]) | ||
|
|
||
| return Ok((next_operation_id,)) |
There was a problem hiding this comment.
artifact_id.to_full_local(argv[0]) constructs an ArtifactSectionId directly and can raise (e.g., if the provided section id contains invalid characters). Since _prepare_arguments doesn’t catch this, a bad goto() argument would crash rendering instead of returning a directive error. Parse/validate argv[0] as a SectionId (or accept an already-parsed SectionId) and return an Err on invalid input.
Comment on lines
+6
to
+11
| - Update artifact references from legacy ids like `specs:intro` to filepath ids like `@/specs/intro.md`, and include file extensions on all artifact references. | ||
|
|
||
| ### Changes | ||
|
|
||
| - Added configurable artifact file filters. Donna will see only files that pass all of the filters. | ||
| - Replaced artifact ids with project-relative filepaths like `@/specs/intro.md` and `@/.donna/session/plans/plan.md:finish`. |
There was a problem hiding this comment.
The migration bullet references @/specs/intro.md, but the repo’s default markdown source extension is now .donna.md (and the docs/examples elsewhere use *.donna.md). Update this example to @/specs/intro.donna.md to avoid suggesting an unsupported artifact id/extension.
Suggested change
| - Update artifact references from legacy ids like `specs:intro` to filepath ids like `@/specs/intro.md`, and include file extensions on all artifact references. | |
| ### Changes | |
| - Added configurable artifact file filters. Donna will see only files that pass all of the filters. | |
| - Replaced artifact ids with project-relative filepaths like `@/specs/intro.md` and `@/.donna/session/plans/plan.md:finish`. | |
| - Update artifact references from legacy ids like `specs:intro` to filepath ids like `@/specs/intro.donna.md`, and include file extensions on all artifact references. | |
| ### Changes | |
| - Added configurable artifact file filters. Donna will see only files that pass all of the filters. | |
| - Replaced artifact ids with project-relative filepaths like `@/specs/intro.donna.md` and `@/.donna/session/plans/plan.md:finish`. |
Comment on lines
+6
to
+11
| - Update artifact references from legacy ids like `specs:intro` to filepath ids like `@/specs/intro.md`, and include file extensions on all artifact references. | ||
|
|
||
| ### Changes | ||
|
|
||
| - Added configurable artifact file filters. Donna will see only files that pass all of the filters. | ||
| - Replaced artifact ids with project-relative filepaths like `@/specs/intro.md` and `@/.donna/session/plans/plan.md:finish`. |
There was a problem hiding this comment.
These example artifact ids use @/.../*.md (e.g. @/specs/intro.md, @/.donna/session/plans/plan.md:finish), but the new artifact discovery and defaults appear to target *.donna.md. Update the examples to use .donna.md so users don’t copy/paste ids that won’t be discoverable/valid by default.
Suggested change
| - Update artifact references from legacy ids like `specs:intro` to filepath ids like `@/specs/intro.md`, and include file extensions on all artifact references. | |
| ### Changes | |
| - Added configurable artifact file filters. Donna will see only files that pass all of the filters. | |
| - Replaced artifact ids with project-relative filepaths like `@/specs/intro.md` and `@/.donna/session/plans/plan.md:finish`. | |
| - Update artifact references from legacy ids like `specs:intro` to filepath ids like `@/specs/intro.donna.md`, and include file extensions on all artifact references. | |
| ### Changes | |
| - Added configurable artifact file filters. Donna will see only files that pass all of the filters. | |
| - Replaced artifact ids with project-relative filepaths like `@/specs/intro.donna.md` and `@/.donna/session/plans/plan.donna.md:finish`. |
Comment on lines
3
to
+6
| - Move project-specific specs from `.donna/project` to `specs`, or set an explicit `project` world path in your Donna workspace config before upgrading. | ||
| - 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. | ||
| - Update artifact references from legacy ids like `specs:intro` to filepath ids like `@/specs/intro.md`, and include file extensions on all artifact references. |
There was a problem hiding this comment.
The migration notes still refer to configuring/migrating “world” paths (e.g. setting an explicit project world path, “filesystem-backed donna world”). Since this PR removes world configuration entirely in favor of filesystem-scoped artifact ids and file_filters, these bullets should be updated to the new model (or removed) to avoid misleading upgrade guidance.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.