Consolidate project runtime state aka .wld/internal by gandazgul · Pull Request #78 · gandazgul/runwield

gandazgul · 2026-09-10T17:12:17Z

Summary

Consolidates machine-owned project runtime state under .wld/internal/ for the 0.11 release. This creates a clear boundary between internal state and project configuration that users can commit.

Plan: https://github.com/gandazgul/runwield/blob/main/docs/plans/consolidate-project-runtime-state.md

What changed

Added one shared runtime layout for primary-checkout and selected-checkout state.
Added a serialized, restart-safe, idempotent migration for supported inactive 0.10 state.
Moved controller records, the worktree registry, publication staging, Plan locks, transition journals, Work Record locks, project collaboration secrets, and the no-HOME worktree fallback to their new owned paths.
Guarded TUI, ACP, headless, Init, Plan, and collaboration entry points so unsafe legacy state blocks before normal reads or writes.
Expanded plans doctor with read-only inspection, actionable migration findings, and safe repair behavior.
Replaced scattered runtime ignore rules with one .wld/internal/ rule and added staging/publication checks that reject current or legacy runtime state in commits and history.
Preserved .wld/settings.json, local Agents, Skills, and prompts as normal project files.
Updated the Core PRD, ADRs, architecture, lifecycle, collaboration, validation, workflow, and usage documentation.

Related workflow fixes included

Epic children are planned from retained target-branch worktrees, so planning sees previously delivered child changes without a manual branch switch.
Pair execution can record user-confirmed Plan Deviations and carry them into Semantic Review and Work Records.
Release hardening permits ordinary repository symlinks while refusing symlinked runtime authorities, preserves non-Git Session behavior, and makes native Windows package qualification a release gate.

Migration and compatibility

This is a one-way 0.11 runtime-layout change.
Supported inactive 0.10 state is adopted automatically on project entry.
Active, conflicting, tracked, malformed, symlinked, or newer state is preserved and reported instead of merged or deleted.
Home state under ~/.wld/ and normal home-based execution worktrees do not move.
Downgrade or mixed-version use after adoption is not supported.

Validation

All eight runtime-state Epic child Plans are marked validated.
The 0.11 release-repair Plan is marked validated.
Native Windows package qualification passed for source a56d754570e7c0ca9b9a43f4fb79c6f3c58ba4fd: workflow run 35242972855.
Candidate publication, isolated Candidate installation checks, and Stable promotion remain release steps after merge and explicit owner approval.

…act execution - Plan: consolidate-project-runtime-state/01-add-runtime-layout-contract - Branch: worktree/consolidate-project-runtime-state-01-add-runtime-a45416fd - Files: docs/plans/consolidate-project-runtime-state/01-add-runtime-layout-contract.md

…ract - Plan: consolidate-project-runtime-state/01-add-runtime-layout-contract - Description: RunWield currently treats the project `.wld/` directory as both user-derived project configuration and machine-owned runtime state. The Epic makes `.wld/internal/` the one current project-runtime root, but the code needs a shared contract before existing stores can move safely. - Branch: worktree/consolidate-project-runtime-state-01-add-runtime-a45416fd - Files: docs/domain-language.md, docs/plans/consolidate-project-runtime-state/01-add-runtime-layout-contract.md, src/constants.js, src/constants.test.js, src/shared/project-runtime-layout.test.ts and 3 more

…ract - Plan: consolidate-project-runtime-state/01-add-runtime-layout-contract - Description: RunWield currently treats the project `.wld/` directory as both user-derived project configuration and machine-owned runtime state. The Epic makes `.wld/internal/` the one current project-runtime root, but the code needs a shared contract before existing stores can move safely. - Branch: worktree/consolidate-project-runtime-state-01-add-runtime-a45416fd - Files: docs/plans/consolidate-project-runtime-state/01-add-runtime-layout-contract.md, src/shared/runwield-owned-paths.test.js, src/shared/runwield-owned-paths.ts

…-add-runtime-layout-contract - Plan: consolidate-project-runtime-state/01-add-runtime-layout-contract - Description: RunWield currently treats the project `.wld/` directory as both user-derived project configuration and machine-owned runtime state. The Epic makes `.wld/internal/` the one current project-runtime root, but the code needs a shared contract before existing stores can move safely. - Branch: worktree/consolidate-project-runtime-state-01-add-runtime-a45416fd - Files: docs/plans/consolidate-project-runtime-state/01-add-runtime-layout-contract.md, docs/plans/consolidate-project-runtime-state/manual-qa.md RunWield-Publication-Attempt: a45416fd RunWield-Publication-Plan-Path: docs/plans/consolidate-project-runtime-state/01-add-runtime-layout-contract.md

…me-a45416fd' into epic/consolidate-project-runtime-state

…tion-engine execution - Plan: consolidate-project-runtime-state/02-add-legacy-runtime-migration-engine - Branch: worktree/consolidate-project-runtime-state-02-add-legacy--4b0163db - Files: docs/plans/consolidate-project-runtime-state/02-add-legacy-runtime-migration-engine.md

…ation-engine - Plan: consolidate-project-runtime-state/02-add-legacy-runtime-migration-engine - Description: Version 0.10.0 must adopt inactive project-local runtime state from legacy `.wld/` paths into `.wld/internal/`. It must stop without changing files when the old state is active, ambiguous, tracked, symlinked, or tied to unfinished publication recovery. - Branch: worktree/consolidate-project-runtime-state-02-add-legacy--4b0163db - Files: docs/plans/consolidate-project-runtime-state/02-add-legacy-runtime-migration-engine.md, src/shared/project-runtime-layout.test.ts, src/shared/project-runtime-layout.ts, src/shared/testing/project-runtime-migration-process-driver.ts, src/shared/workflow/publication-attempt.test.ts and 3 more

…ation-engine - Plan: consolidate-project-runtime-state/02-add-legacy-runtime-migration-engine - Description: Version 0.10.0 must adopt inactive project-local runtime state from legacy `.wld/` paths into `.wld/internal/`. It must stop without changing files when the old state is active, ambiguous, tracked, symlinked, or tied to unfinished publication recovery. - Branch: worktree/consolidate-project-runtime-state-02-add-legacy--4b0163db - Files: docs/plans/consolidate-project-runtime-state/02-add-legacy-runtime-migration-engine.md, src/plan-store.js, src/shared/lock-file-snapshot.ts, src/shared/project-runtime-layout.test.ts, src/shared/project-runtime-layout.ts and 4 more

…-add-legacy-runtime-migration-engine - Plan: consolidate-project-runtime-state/02-add-legacy-runtime-migration-engine - Description: Version 0.10.0 must adopt inactive project-local runtime state from legacy `.wld/` paths into `.wld/internal/`. It must stop without changing files when the old state is active, ambiguous, tracked, symlinked, or tied to unfinished publication recovery. - Branch: worktree/consolidate-project-runtime-state-02-add-legacy--4b0163db - Files: docs/plans/consolidate-project-runtime-state/02-add-legacy-runtime-migration-engine.md, docs/plans/consolidate-project-runtime-state/manual-qa.md RunWield-Publication-Attempt: 4b0163db RunWield-Publication-Plan-Path: docs/plans/consolidate-project-runtime-state/02-add-legacy-runtime-migration-engine.md

…ld publication

…y--4b0163db' into epic/consolidate-project-runtime-state

…res execution - Plan: consolidate-project-runtime-state/03-move-primary-runtime-stores - Branch: worktree/consolidate-project-runtime-state-03-move-primar-f995640a - Files: docs/plans/consolidate-project-runtime-state/03-move-primary-runtime-stores.md

…ores - Plan: consolidate-project-runtime-state/03-move-primary-runtime-stores - Description: Primary-owned runtime state is shared through the primary checkout. Today, several stores still construct paths under `.wld/` directly or inherit the old runtime directory. They must move under the primary checkout's `.wld/internal/` root. - Branch: worktree/consolidate-project-runtime-state-03-move-primar-f995640a - Files: docs/plans/consolidate-project-runtime-state/03-move-primary-runtime-stores.md, src/cmd/load-plan/plan-recovery-flow.test.ts, src/cmd/plans/doctor.test.ts, src/plan-store.test.js, src/shared/project-runtime-layout.test.ts and 15 more

greptile-apps

Your trial has ended. Reactivate Greptile to resume code reviews.

…ores - Plan: consolidate-project-runtime-state/03-move-primary-runtime-stores - Description: Primary-owned runtime state is shared through the primary checkout. Today, several stores still construct paths under `.wld/` directly or inherit the old runtime directory. They must move under the primary checkout's `.wld/internal/` root. - Branch: worktree/consolidate-project-runtime-state-03-move-primar-f995640a - Files: docs/plans/consolidate-project-runtime-state/03-move-primary-runtime-stores.md, src/shared/project-runtime-layout.test.ts, src/shared/project-runtime-layout.ts, src/shared/workflow/publication-machine.ts, src/shared/worktree-registry.js and 1 more

…-move-primary-runtime-stores - Plan: consolidate-project-runtime-state/03-move-primary-runtime-stores - Description: Primary-owned runtime state is shared through the primary checkout. Today, several stores still construct paths under `.wld/` directly or inherit the old runtime directory. They must move under the primary checkout's `.wld/internal/` root. - Branch: worktree/consolidate-project-runtime-state-03-move-primar-f995640a - Files: docs/plans/consolidate-project-runtime-state/03-move-primary-runtime-stores.md, docs/plans/consolidate-project-runtime-state/manual-qa.md RunWield-Publication-Attempt: f995640a RunWield-Publication-Plan-Path: docs/plans/consolidate-project-runtime-state/03-move-primary-runtime-stores.md

…ar-f995640a' into epic/consolidate-project-runtime-state

- Plan: record-pair-plan-deviations - Branch: worktree/record-pair-plan-deviations-f00ee389 - Files: docs/plans/record-pair-plan-deviations.md

…untime-stores execution - Plan: consolidate-project-runtime-state/04-move-selected-checkout-runtime-stores - Branch: worktree/consolidate-project-runtime-state-04-move-select-368eca2f - Files: docs/plans/consolidate-project-runtime-state/04-move-selected-checkout-runtime-stores.md

- Plan: record-pair-plan-deviations - Description: Pair Execution lets the user inspect an increment and change direction before implementation continues. Today, revision feedback returns only to the live Plan Engineer or Frontend Engineer turn. The Session Transcript can retain the tool result, and optional metrics retain a content-free decision, but neither is Plan authority. A restart, Semantic Code Review, or Work Record generation has no structured record that the user intentionally replaced a Plan requirement. The Reviewer can then reject correct code for not matching obsolete Plan text. - Branch: worktree/record-pair-plan-deviations-f00ee389 - Files: docs/domain-language.md, docs/plan-workflow-map.md, docs/plans/record-pair-plan-deviations.md, docs/validation-authority.md, docs/workflows.md and 33 more

…runtime-stores - Plan: consolidate-project-runtime-state/04-move-selected-checkout-runtime-stores - Description: Plan document locks, catalog locks, transition journals, and Work Record supersession locks are selected-checkout state. They protect the checkout that owns the document mutation or checkout-local operation. Today they use the old `.wld/` runtime location. - Branch: worktree/consolidate-project-runtime-state-04-move-select-368eca2f - Files: docs/plans/consolidate-project-runtime-state/04-move-selected-checkout-runtime-stores.md, src/cmd/plans/doctor.test.ts, src/cmd/plans/doctor.ts, src/plan-store.js, src/plan-store.test.js and 7 more

- Plan: fix-epic-branch-loading-and-child-planning - Branch: worktree/fix-epic-branch-loading-and-child-planning-6ba3cf38 - Files: docs/plans/fix-epic-branch-loading-and-child-planning.md

…runtime-stores - Plan: consolidate-project-runtime-state/04-move-selected-checkout-runtime-stores - Description: Plan document locks, catalog locks, transition journals, and Work Record supersession locks are selected-checkout state. They protect the checkout that owns the document mutation or checkout-local operation. Today they use the old `.wld/` runtime location. - Branch: worktree/consolidate-project-runtime-state-04-move-select-368eca2f - Files: docs/plans/consolidate-project-runtime-state/04-move-selected-checkout-runtime-stores.md, src/cmd/load-plan/plan-recovery-flow.test.ts, src/shared/git-test-fixture.ts, src/shared/work-records/supersession.test.ts, src/shared/workflow/plan-location.integration.test.ts and 1 more

…-move-selected-checkout-runtime-stores - Plan: consolidate-project-runtime-state/04-move-selected-checkout-runtime-stores - Description: Plan document locks, catalog locks, transition journals, and Work Record supersession locks are selected-checkout state. They protect the checkout that owns the document mutation or checkout-local operation. Today they use the old `.wld/` runtime location. - Branch: worktree/consolidate-project-runtime-state-04-move-select-368eca2f - Files: docs/plans/consolidate-project-runtime-state/04-move-selected-checkout-runtime-stores.md, docs/plans/consolidate-project-runtime-state/manual-qa.md RunWield-Publication-Attempt: 368eca2f RunWield-Publication-Plan-Path: docs/plans/consolidate-project-runtime-state/04-move-selected-checkout-runtime-stores.md

…ct-368eca2f' into epic/consolidate-project-runtime-state

- Plan: fix-epic-branch-loading-and-child-planning - Description: An Epic can publish its children to a branch while the user keeps the primary checkout on another branch. Today the user must switch that checkout to see current child statuses with `/load-plan`. Automatic continuation can select a child before publication cleanup, then reload it and start Planner in the primary checkout. Planner sees old statuses and cannot see code delivered by earlier children. - Branch: worktree/fix-epic-branch-loading-and-child-planning-6ba3cf38 - Files: docs/adr/005-concurrent-worktree-isolation.md, docs/domain-language.md, docs/plans/fix-epic-branch-loading-and-child-planning.md, docs/usage.md, src/cmd/load-plan/index.ts and 10 more

- Plan: record-pair-plan-deviations - Description: Pair Execution lets the user inspect an increment and change direction before implementation continues. Today, revision feedback returns only to the live Plan Engineer or Frontend Engineer turn. The Session Transcript can retain the tool result, and optional metrics retain a content-free decision, but neither is Plan authority. A restart, Semantic Code Review, or Work Record generation has no structured record that the user intentionally replaced a Plan requirement. The Reviewer can then reject correct code for not matching obsolete Plan text. - Branch: worktree/record-pair-plan-deviations-f00ee389 - Files: docs/domain-language.md, docs/plan-workflow-map.md, docs/plans/record-pair-plan-deviations.md, docs/validation-authority.md, docs/workflows.md and 12 more

- Plan: record-pair-plan-deviations - Description: Pair Execution lets the user inspect an increment and change direction before implementation continues. Today, revision feedback returns only to the live Plan Engineer or Frontend Engineer turn. The Session Transcript can retain the tool result, and optional metrics retain a content-free decision, but neither is Plan authority. A restart, Semantic Code Review, or Work Record generation has no structured record that the user intentionally replaced a Plan requirement. The Reviewer can then reject correct code for not matching obsolete Plan text. - Branch: worktree/record-pair-plan-deviations-f00ee389 - Files: docs/plans/record-pair-plan-deviations.md RunWield-Publication-Attempt: f00ee389 RunWield-Publication-Plan-Path: docs/plans/record-pair-plan-deviations.md

…ct-361fae63' into epic/consolidate-project-runtime-state # Conflicts: # docs/prd/runwield-core-prd.md

- Plan: release-runtime-state-v0-11-0 - Branch: worktree/release-runtime-state-v0-11-0-494f198b - Files: docs/plans/release-runtime-state-v0-11-0.md

# Conflicts: # src/plan-store.test.js

# Conflicts: # scripts/release-policy.test.js

- Plan: release-runtime-state-v0-11-0 - Description: The [runtime-state Epic](consolidate-project-runtime-state.md) reports all eight children complete. Release review of `83d1c205` against `main` at `f7c2c9d8` found remaining safety gaps. The owner also observed publication stop at `CLAUDE.md`, a repository symlink to `AGENTS.md`. The other findings below are source-review findings, not yet reproduced by this planning session. No current full-suite or merge-result qualification is claimed. - Branch: worktree/release-runtime-state-v0-11-0-494f198b - Files: docs/plans/release-runtime-state-v0-11-0.md

- Plan: release-runtime-state-v0-11-0 - Description: The [runtime-state Epic](consolidate-project-runtime-state.md) reports all eight children complete. Release review of `83d1c205` against `main` at `f7c2c9d8` found remaining safety gaps. The owner also observed publication stop at `CLAUDE.md`, a repository symlink to `AGENTS.md`. The other findings below are source-review findings, not yet reproduced by this planning session. No current full-suite or merge-result qualification is claimed. - Branch: worktree/release-runtime-state-v0-11-0-494f198b - Files: .gitignore, docs/plans/release-runtime-state-v0-11-0.md, src/ui/workspace/server/astro-canonical-data.js, src/ui/workspace/server/astro-owner-data.js

- Plan: release-runtime-state-v0-11-0 - Description: The [runtime-state Epic](consolidate-project-runtime-state.md) reports all eight children complete. Release review of `83d1c205` against `main` at `f7c2c9d8` found remaining safety gaps. The owner also observed publication stop at `CLAUDE.md`, a repository symlink to `AGENTS.md`. The other findings below are source-review findings, not yet reproduced by this planning session. No current full-suite or merge-result qualification is claimed. - Branch: worktree/release-runtime-state-v0-11-0-494f198b - Files: docs/plans/release-runtime-state-v0-11-0.md RunWield-Publication-Attempt: 494f198b RunWield-Publication-Plan-Path: docs/plans/release-runtime-state-v0-11-0.md

…pic/consolidate-project-runtime-state

…ect-runtime-state # Conflicts: # src/cmd/plans/index.ts

gandazgul added 13 commits September 7, 2026 17:57

Merge branch 'worktree/consolidate-project-runtime-state-01-add-runti…

7b2cc4f

…me-a45416fd' into epic/consolidate-project-runtime-state

Integrate origin/epic/consolidate-project-runtime-state before RunWie…

d5150de

…ld publication

Merge branch 'worktree/consolidate-project-runtime-state-02-add-legac…

63aa789

…y--4b0163db' into epic/consolidate-project-runtime-state

greptile-apps Bot reviewed Sep 10, 2026

View reviewed changes

gandazgul marked this pull request as draft September 10, 2026 17:12

gandazgul added 15 commits September 10, 2026 15:05

Merge branch 'worktree/consolidate-project-runtime-state-03-move-prim…

759f744

…ar-f995640a' into epic/consolidate-project-runtime-state

Merge branch 'main' into epic/consolidate-project-runtime-state

4b79204

Prepare record-pair-plan-deviations execution

9ae3465

- Plan: record-pair-plan-deviations - Branch: worktree/record-pair-plan-deviations-f00ee389 - Files: docs/plans/record-pair-plan-deviations.md

Prepare fix-epic-branch-loading-and-child-planning execution

d9923c6

- Plan: fix-epic-branch-loading-and-child-planning - Branch: worktree/fix-epic-branch-loading-and-child-planning-6ba3cf38 - Files: docs/plans/fix-epic-branch-loading-and-child-planning.md

Merge branch 'worktree/consolidate-project-runtime-state-04-move-sele…

c51a768

…ct-368eca2f' into epic/consolidate-project-runtime-state

gandazgul added 14 commits September 16, 2026 16:09

Merge branch 'worktree/consolidate-project-runtime-state-08-update-do…

83d1c20

…ct-361fae63' into epic/consolidate-project-runtime-state # Conflicts: # docs/prd/runwield-core-prd.md

Prepare release-runtime-state-v0-11-0 execution

d9b3cf3

- Plan: release-runtime-state-v0-11-0 - Branch: worktree/release-runtime-state-v0-11-0-494f198b - Files: docs/plans/release-runtime-state-v0-11-0.md

Repair runtime state release readiness

234bef3

Merge origin/main into runtime state release candidate

236ee90

# Conflicts: # src/plan-store.test.js

Keep migration lock readable on Windows

2a6c9ca

Release lock snapshots safely on Windows

0a6a1bc

Keep non-Git Sessions outside project runtime

004e572

Skip unsupported Windows directory sync

6dadb56

Use current runtime ignore in package smoke

a56d754

Record native Windows qualification

fd9be16

Validate Windows migration journal lock paths

21f2ad1

Wait for publication failure evidence

77f6bfd

Merge latest origin/main into runtime state release candidate

9f3ef91

# Conflicts: # scripts/release-policy.test.js

gandazgul added this to the mjfdszaertyy890--098ytresaAsdrtyuio0p-[==[-p0o9i8uytresaAWESRT7Y8U9I0O-[098UYTRESAASderdtyu890-p=-098uytresaASerty8u90-=-098uy7tredsasrtyu8u90-[=-08ytreassertyui milestone Sep 17, 2026

gandazgul added 3 commits September 17, 2026 18:40

Merge branch 'worktree/release-runtime-state-v0-11-0-494f198b' into e…

4840beb

…pic/consolidate-project-runtime-state

gandazgul changed the title ~~Epic/consolidate project runtime state~~ Consolidate project runtime state aka .wld/internal Sep 17, 2026

gandazgul removed this from the mjfdszaertyy890--098ytresaAsdrtyuio0p-[==[-p0o9i8uytresaAWESRT7Y8U9I0O-[098UYTRESAASderdtyu890-p=-098uytresaASerty8u90-=-098uy7tredsasrtyu8u90-[=-08ytreassertyui milestone Sep 17, 2026

gandazgul added 9 commits September 17, 2026 19:07

Merge main into epic/consolidate-project-runtime-state

7b72def

Skip Homebrew test on Linux

9db22b1

Merge remote-tracking branch 'origin/main' into epic/consolidate-proj…

310060d

…ect-runtime-state # Conflicts: # src/cmd/plans/index.ts

Fix PR standards violations

b3c9ac5

Restore internal runtime ignore boundary

fe93d12

Stabilize worktree abandonment scenario

3d893dc

Stabilize PR Golden TUI gate

f2a3fd8

Allow semantic nudge workflow to settle

9c1db13

Wait for load-plan terminal readiness

22fb0fd

gandazgul marked this pull request as ready for review September 18, 2026 13:05

Navigation Menu

Consolidate project runtime state aka .wld/internal - #78

Consolidate project runtime state aka .wld/internal#78
gandazgul wants to merge 80 commits into
mainfrom
epic/consolidate-project-runtime-state

gandazgul commented Sep 10, 2026 •

edited

Loading

Uh oh!

greptile-apps Bot left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

gandazgul commented Sep 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What changed

Related workflow fixes included

Migration and compatibility

Validation

Uh oh!

greptile-apps Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

gandazgul commented Sep 10, 2026 •

edited

Loading