Add named Repository and Worktree composition

Story

As a workflow author, I want named Repositories and optional named Worktrees composed inside one retained Workspace, so one workflow can operate on multiple repositories without implicit repository-name resolution or a magical first directory.

Contract

Repository creates or attaches a normal primary checkout inside the Workspace. Its lexical form establishes cwd for descendants; its self-closing form returns a Workspace-relative path binding. Repository URLs and bases come from ordinary root props or expressions—names do not resolve configuration implicitly.

Worktree creates a named Git worktree for the contextual Repository. Its name is its stable identity within the Workspace. It checks out the default branch when base is absent or the specified base when present, then switches to the requested new branch. A Worktree may lexically contain any components, including Agent.

Dir remains lexical cwd only. Agent-readable directory registration belongs to Agent.AddDir in #302.

Worktrees are retained with the WorkflowRun. Cleanup is explicit; success does not silently delete useful state. A worktree is composition and isolation, not a security boundary.

Acceptance

One Workspace can retain two Repositories and Worktrees from different remotes without path or identity collision.
Repository and Worktree names are explicit stable component identities, not magic configuration lookup keys.
Root props and expressions may supply repository, base, branch, and path values.
Omitted Repository base uses the remote default branch.
Worktree checkout follows the selected base and then switches to its new named branch.
Lexical forms establish contextual cwd for all descendants.
Self-closing forms return Workspace-relative paths without changing later cwd.
Replay restores metadata and paths without recreating a completed checkout effect.
Missing or conflicting retained Git state fails explicitly.
Deletion or cleanup reports retained dirty, unpushed, or conflicting work and never discards it implicitly.

Dependencies

Add the xmd workflow start/resume filesystem vertical slice #366 supplies the retained Workspace execution path.
Commit Workspace mutations and journal results atomically #365 supplies atomic local mutations and metadata publication.
PR 📝 Specify retained workflow Workspaces #358 supplies the Repository and Worktree composition contract.
End goal: ✨ Compose and certify the supervised adversarial implementation workflow #181.

📝 Align the target with #203 as merged and restore the printing contract

💥 Replace invocation() with getExpansion() and derive expansion identity

💥 Add expansion identity and pinned-commit workflow runs (#341)

Architecture note from #181 reorientation: Git provider strategy

Repository and Worktree should stay provider-neutral. The first local Deno workflow provider should use native Git because it gives the most faithful checkout, worktree, object-cache and performance behavior for the #181 path.

isomorphic-git is a candidate provider implementation, primarily for browser/playground execution, not the language contract. If a provider cannot expose native git-worktree semantics, it may emulate named Worktrees as separate retained working directories/checkouts, as long as the observable Repository/Worktree contract remains the same.

Initial checkout performance should be provider-owned acceleration, not durable identity. A Deno provider may use a host-local mirror/object cache outside the WorkflowRun database. Cache presence may change speed only. The run still records its own Repository identity, pinned/default base, retained Workspace path, and checkout/worktree metadata. Completed replay must not reclone; partial replay reattaches the retained checkout and verifies enough state to continue. Missing or corrupt retained Git state fails explicitly instead of silently creating a replacement.

📝 Align the target with #203 as merged and restore the printing contract

Architecture clarification: binding a checkout path while rendering descendants

PR #181 exposed an apparent conflict between two already-settled contracts:

executable-MDX §6.2/§6.5/§6.9 makes a generic component invocation as="name" a private capture: the invocation binds its result and contributes no output at the call site; and
this issue and specs/workflow-workspace-spec.md distinguish lexical Repository/Worktree forms, which establish cwd for their children, from self-closing forms, which return the stable Workspace-relative checkout path.

The distinction is intentional and resolves the conflict. Generic as= remains unchanged. Repository and Worktree receive no exception that both binds a path and renders the same invocation's children. A lexical <Worktree ... as="worktree">...</Worktree> would therefore capture that invocation on the ordinary binding terms; it cannot mean “bind the path but also emit the children.”

When a workflow needs both the path and lexical cwd, it composes the two existing forms inside the enclosing Repository:

<Repository name="project" url={props.repository} base={props.base}>
  <Worktree name="implementation" branch={props.branch} as="worktree" />
  <Dir path={worktree}>
    <!-- workflow stages and final report -->
  </Dir>
</Repository>

The self-closing Worktree creates or restores the named retained checkout and binds its Workspace-relative path without changing later cwd. The following lexical Dir establishes that path as cwd for the complete stage flow and renders its children normally. It remains inside the lexical Repository, so the Repository context required by Worktree and later Git/forge composition remains present. Agent.AddDir continues to receive the explicit worktree path and remains distinct from cwd.

Consequences for #293:

implement and test the lexical/self-closing split already stated in the issue;
include the specified lexical Dir composition boundary needed to consume a self-closing checkout path, unless an earlier production issue supplies it first;
prove the composed spelling binds the stable path, runs descendants under that cwd, emits their rendered output once, restores the enclosing cwd, and replays without recreating a completed checkout effect; and
keep the generic component-binding regressions unchanged. No component name, registration identity, host installation, or Workspace provider may change what as= means.

Consequences for PR #181: replace the combined lexical <Worktree ... as="worktree">...</Worktree> with the explicit self-closing Worktree plus lexical Dir composition above, and keep the final-gate report inside Dir and the root Output region. No main runtime mechanism is selected or implemented by that documentation PR.

📝 Align the target with #203 as merged and restore the printing contract

📝 Compose the checkout path and the directory it is worked in

Maintainer amendment: extend schema version 1 in place

The project is pre-release and has no users or retained-run compatibility obligation. #293 therefore does not introduce another workflow database schema version.

Repository and Worktree metadata are added to schema version 1 in place. The version remains 1, strict schema recognition is updated to the new complete shape, and fixtures/tests that describe the old development-only shape move with it. No migration, legacy-reader path, dual-schema support, compatibility alias, or upgrade behavior is added.

This is an explicit persistence-boundary amendment to the earlier statement that version 1 was complete. After #293, the amended schema is the one and only complete version-1 shape. A database produced by an older development build may be refused as damaged/incomplete; preserving it is outside the supported pre-release contract.

Public run deletion remains owned by #367. #293 retains Repository/Worktree state with the WorkflowRun and proves that successful completion and attachment teardown do not delete it; it does not add a second deletion lifecycle.

📝 Align the target with #203 as merged and restore the printing contract

📝 Compose the checkout path and the directory it is worked in

📝 Record the composition and the lifecycle authority as shipped

🔒 Give a workflow Agent nothing but what its prompt renders

📝 Align the target with #203 as merged and restore the printing contract

📝 Compose the checkout path and the directory it is worked in

📝 Record the composition and the lifecycle authority as shipped

🔒 Give a workflow Agent nothing but what its prompt renders

📝 Align the target with #203 as merged and restore the printing contract

📝 Compose the checkout path and the directory it is worked in

📝 Record the composition and the lifecycle authority as shipped

🔒 Give a workflow Agent nothing but what its prompt renders

📝 Align the target with #203 as merged and restore the printing contract

📝 Compose the checkout path and the directory it is worked in

📝 Record the composition and the lifecycle authority as shipped

🔒 Give a workflow Agent nothing but what its prompt renders

Navigation Menu

Repository navigation

Add named Repository and Worktree composition #293

Story

Contract

Acceptance

Dependencies

Architecture clarification: binding a checkout path while rendering descendants

Maintainer amendment: extend schema version 1 in place

68 remaining items

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Add named Repository and Worktree composition #293

Description

Story

Contract

Acceptance

Dependencies

Activity

taras commented on Aug 10, 2026

taras commented on Aug 13, 2026

Architecture clarification: binding a checkout path while rendering descendants

taras commented on Aug 13, 2026

Maintainer amendment: extend schema version 1 in place

68 remaining items

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions