Store branch artifacts in the semantic Tree hierarchy

README.md

@@ -268,9 +268,10 @@ make validate
 
 ## Status
 
-`v0.1.6` is the current version. Alignment, declarative Tree construction,
-protected branch traversal, Recall, Project Map, and Replay form a usable
-end-to-end loop. Project Map interaction design will continue to evolve.
+`v0.1.7` is the current version. Alignment, declarative Tree construction,
+hierarchy-aligned branch documents, protected branch traversal, Recall, Project
+Map, and Replay form a usable end-to-end loop. Project Map interaction design
+will continue to evolve.
 
 ## Privacy
 

README.zh-CN.md

@@ -246,9 +246,9 @@ make validate
 
 ## 当前状态
 
-`v0.1.6` 是当前版本。Alignment、声明式 Tree 构建、受保护的 branch 移动、
-Recall、Project Map 和 Replay 已经形成可用的端到端闭环。Project Map 的交互
-设计仍会持续演化。
+`v0.1.7` 是当前版本。Alignment、声明式 Tree 构建、与 Tree 层级一致的 branch
+文档、受保护的 branch 移动、Recall、Project Map 和 Replay 已经形成可用的
+端到端闭环。Project Map 的交互设计仍会持续演化。
 
 ## 隐私
 

RELEASE-NOTES.md

@@ -1,5 +1,17 @@
 # Release Notes
 
+## v0.1.7 - Hierarchical Branch Artifacts
+
+- Projects branch documents onto the same parent-child hierarchy as the
+  accepted Tree, keeping each branch's Spec, Plan, Progress, Findings,
+  Verification, and auxiliary evidence together.
+- Migrates the legacy flat layout on the first protected mutation while keeping
+  read-only Recall and Project Map compatible before migration.
+- Moves parent branches and all descendants atomically during Tree Apply, with
+  journaled rollback and collision, cycle, escape, and symlink validation.
+- Routes CLI lifecycle operations, managed worktrees, Recall, Project Map, MCP,
+  and release fixtures through one shared branch-artifact resolver.
+
 ## v0.1.6 - Atomic macOS Upgrade Publication
 
 - Publishes the rebuilt CLI through a fresh sibling file and atomic rename

docs/README.md

@@ -33,6 +33,9 @@ These files live under
 - [Transaction and projection](architecture/transaction-projection.md) defines
   publication, events, checkpoints, coherent reads, watchers, and Replay
   reconstruction.
+- [Hierarchical branch artifacts](architecture/hierarchical-branch-artifacts.md)
+  defines the Tree-derived document layout, legacy migration, subtree moves,
+  and rollback contract.
 
 ## Contributors
 

docs/architecture/hierarchical-branch-artifacts.md

@@ -0,0 +1,87 @@
+# Hierarchical Branch Artifacts
+
+TreeWork's semantic Tree and its branch-document filesystem must describe the
+same project shape. In TreeWork 0.1.6, branch state is hierarchical while
+branch documents are stored in a flat `.TreeWork/branches/<branch-id>/`
+directory. A custom Spec path can additionally split one branch's documents
+between two locations.
+
+TreeWork 0.1.7 replaces that split model with a deterministic filesystem
+projection of the accepted Tree.
+
+## Storage Contract
+
+Branch identity and branch location are intentionally separate:
+
+- the branch ID is the stable identity used by commands, events, dependencies,
+  Replay, and worktree bindings;
+- the artifact directory is derived from the branch's accepted parent chain;
+- the derived path is never persisted as a second topology source;
+- root documents remain directly under `.TreeWork/`;
+- every non-root branch owns `spec.md`, `task_plan.md`, `progress.md`,
+  `findings.md`, and `verification.md` in one directory.
+
+For example:
+
+```text
+.TreeWork/
+├── spec.md
+├── task_plan.md
+├── progress.md
+├── findings.md
+└── branches/
+    └── public-release-adoption/
+        ├── spec.md
+        ├── task_plan.md
+        ├── progress.md
+        ├── findings.md
+        ├── verification.md
+        └── release-maintenance/
+            ├── spec.md
+            ├── task_plan.md
+            ├── progress.md
+            ├── findings.md
+            └── verification.md
+```
+
+Each branch ID is encoded as one filesystem segment. Lowercase ASCII letters,
+digits, `-`, and `_` remain literal. Every other allowed byte is percent
+encoded, including `.` and `/`. This preserves a one-to-one mapping and stops
+an ID from creating undeclared levels or colliding with managed filenames.
+
+## Layout Versions
+
+`state/project.json` records `artifact_layout_version`:
+
+- missing or `1` means the legacy flat layout;
+- `2` means the hierarchy derived from accepted parent relationships.
+
+Read-only operations understand both layouts and never migrate implicitly.
+The first locked mutation of a legacy project performs a protected one-time
+migration. New projects start at layout version 2.
+
+Migration moves every branch-owned file, not just the five standard Markdown
+documents. Custom Specs become the canonical `spec.md` for their branch.
+Branch IDs, lifecycle state, verification, dependencies, event sequence, Tree
+revision, and worktree bindings do not change. `.TreeWork/archive/` is outside
+the live resolver and is never migrated.
+
+## Tree Apply
+
+Tree Apply compares the committed layout with the candidate layout. Moving a
+branch under another parent also changes the path of every descendant. Apply
+therefore stages affected directories deepest-first and publishes them
+shallowest-first inside the existing publication transaction.
+
+No non-identical destination may be overwritten. Symlinks, paths escaping the
+branches root, missing parents, cycles, and duplicate destinations fail closed.
+Before the publication marker, any failure restores the exact previous paths
+and bytes. After the durable marker, recovery only finishes the accepted state
+forward.
+
+## Runtime Rule
+
+All consumers use the same resolver: scaffolding, lifecycle commands, Recall,
+completion validation, managed worktrees, Project Map narratives and watchers,
+MCP delegation, hooks, fixtures, and packaging tests. Production code must not
+construct `.TreeWork/branches/<branch-id>` directly.

docs/development.md

@@ -72,6 +72,9 @@ python3 /path/to/skill-creator/scripts/quick_validate.py \
 - Edit Agent workflow guidance under the plugin Skill.
 - Edit developer contracts under `docs/`.
 - Do not manually edit `.TreeWork/state/` or managed progress blocks.
+- Do not construct flat `.TreeWork/branches/<branch-id>/` paths in runtime or
+  tests. Resolve branch artifacts from the accepted semantic Tree so nested
+  branches and legacy layout migration share one contract.
 
 Run `make test` for the normal suite and `make validate` for release-facing
 structure and packaging checks.

plugins/treework/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "treework",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "State-native project memory for long-running coding agents.",
   "author": {
     "name": "Zhongxuan Song",

plugins/treework/crates/treework-cli/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "treework-cli"
-version = "0.1.6"
+version = "0.1.7"
 edition = "2021"
 authors = ["Zhongxuan Song <universeszym@mail.ustc.edu.cn>"]
 description = "TreeWork state, transaction, and Project Map runtime"