T-C9RD-consolidate-augmented-into-solutions

Status: closed/done · Impact: high · Complexity: large

Goal

The augmented family (5 apps + ~10 shared packages) was adopted flat into apps/ and packages/{ts,rust}/, where a single-solution cluster is indistinguishable from repo-wide shared libraries. Relocate it into a solutions/augmented/ sub-project — the reference application of D-0001’s new solutions/ tier (T-1YSW) — so the cluster’s sharing scope is legible and each package can later earn packages/ by observed cross-solution use. Package NAMES stay unchanged, so workspace:* / { workspace = true } specifiers barely move.

Today

Location	Role today
`apps/augmented-books/`	Tauri desktop app (Rust `src-tauri/` + `runners/sqlite/builder/`), adopted flat into `apps/`
`apps/augmented_dot_com/`	Augmented marketing/web app, flat in `apps/`
`apps/augmented_web/`	Augmented web app, flat in `apps/`; an explicit root `workspaces` member
`apps/learn_web/`	Nuxt learn app, flat in `apps/`; an explicit root `workspaces` member
`apps/vimit_prototype/`	Vimit prototype app, flat in `apps/`; an explicit root `workspaces` member
`packages/ts/entity/`	Augmented shared TS package, flat in `packages/ts/` (also: `books`, `context`, `hierarchy`, `json-canvas-core`, `json-canvas-vue` + its `demo/`, `test-vue-component`, `logging`, `utils`) — consumed only by the augmented apps
`packages/rust/augmented-common/`	Augmented shared Rust crate, a member via the `packages/rust/*` glob
`package.json`	Root Bun `workspaces`: explicit `apps/augmented_web`, `apps/learn_web`, `apps/vimit_prototype`, the `packages/ts/*` glob, and the `packages/ts/json-canvas-vue/demo` glob
`Cargo.toml`	Root `members`: `packages/rust/*`, `apps/augmented-books/src-tauri`, `apps/augmented-books/runners/sqlite/builder`
`.moon/workspace.yml`	`projects.globs`: `apps/`, `packages/ts/`, `packages/rust/`, `sites/`, `tools/*`

Proposed

A solutions/augmented/ sub-project with a nested apps/ + packages/{ts,rust}/, holding all 5 apps and the surviving packages at the sub-paths below. Root workspaces, Cargo members, and moon projects.globs glob the solutions/* tier so every moved project resolves at its new source with the same package name; bun install and cargo metadata --locked re-resolve additively (paths change, versions do not). render, frontmatter-validator, and obsidian-bases-augment are already gone via T-J5DI.

Approach

Scaffold solutions/augmented/apps/, solutions/augmented/packages/ts/, and solutions/augmented/packages/rust/.
Move the 5 apps (git mv) into solutions/augmented/apps/: augmented-books (with its src-tauri/ and runners/sqlite/builder/), augmented_dot_com, augmented_web, learn_web, vimit_prototype.
Move the surviving packages into solutions/augmented/packages/ts/: books, context, entity, hierarchy, json-canvas-core, json-canvas-vue (with its demo/), test-vue-component, logging, utils; and packages/rust/augmented-common → solutions/augmented/packages/rust/augmented-common.
Root package.json workspaces: drop the explicit apps/augmented_web, apps/learn_web, apps/vimit_prototype entries and the moved packages/ts/json-canvas-vue/demo glob; add solutions/*/apps/*, solutions/*/packages/ts/*, and solutions/*/packages/ts/*/demo. Leave packages/ts/obsidian-bases/demo (not moving).
Root Cargo.toml members: replace apps/augmented-books/src-tauri and apps/augmented-books/runners/sqlite/builder with the glob solutions/*/apps/*/src-tauri, an explicit solutions/augmented/apps/augmented-books/runners/sqlite/builder (the nested builder crate the src-tauri glob does not reach), and solutions/*/packages/rust/* (augmented-common leaves the packages/rust/* glob when it moves). Additive only — stop and record if any pin is forced.
.moon/workspace.yml: add solutions/*/apps/* and solutions/*/packages/*/* to projects.globs; verify/fix any moved project’s moon.yml that hard-codes a source path (moon derives source from the glob location, so most need no edit).
Fix relative filesystem references broken by the added directory depth (apps/<x> → solutions/augmented/apps/<x> is two levels deeper): tsconfig extends/path references, bundler (Nuxt/Vite) watch/alias paths, Tauri src-tauri config paths. workspace:* / { workspace = true } specifiers resolve by NAME and are unaffected.
Re-resolve locks: root bun install and cargo metadata --locked (exit 0). Confirm moon query projects lists every moved project at its new source, and that each moved app still typechecks/builds.
Update documentation broken by the move: fix root-relative paths in the augmented-books README and its docs/, then regenerate the generated docs/site so rosters reference the new sources.

Files to touch

Location	Kind	Change
`apps/augmented-books/`	delete	Move → `solutions/augmented/apps/augmented-books/` (incl. `src-tauri/` + `runners/sqlite/builder/`)
`apps/augmented_dot_com/`	delete	Move → `solutions/augmented/apps/augmented_dot_com/`
`apps/augmented_web/`	delete	Move → `solutions/augmented/apps/augmented_web/`
`apps/learn_web/`	delete	Move → `solutions/augmented/apps/learn_web/`
`apps/vimit_prototype/`	delete	Move → `solutions/augmented/apps/vimit_prototype/`
`packages/ts/books/`	delete	Move → `solutions/augmented/packages/ts/books/`
`packages/ts/context/`	delete	Move → `solutions/augmented/packages/ts/context/`
`packages/ts/entity/`	delete	Move → `solutions/augmented/packages/ts/entity/`
`packages/ts/hierarchy/`	delete	Move → `solutions/augmented/packages/ts/hierarchy/`
`packages/ts/json-canvas-core/`	delete	Move → `solutions/augmented/packages/ts/json-canvas-core/`
`packages/ts/json-canvas-vue/`	delete	Move → `solutions/augmented/packages/ts/json-canvas-vue/` (incl. `demo/`)
`packages/ts/test-vue-component/`	delete	Move → `solutions/augmented/packages/ts/test-vue-component/`
`packages/ts/logging/`	delete	Move → `solutions/augmented/packages/ts/logging/`
`packages/ts/utils/`	delete	Move → `solutions/augmented/packages/ts/utils/`
`packages/rust/augmented-common/`	delete	Move → `solutions/augmented/packages/rust/augmented-common/`
`solutions/augmented/`	new	New solution root: nested `apps/` + `packages/{ts,rust}/` housing the moved augmented family
`package.json`	modify	Drop explicit `apps/augmented_web`, `apps/learn_web`, `apps/vimit_prototype` and the `packages/ts/json-canvas-vue/demo` glob from `workspaces`; add `solutions//apps/`, `solutions//packages/ts/`, `solutions//packages/ts//demo`
`Cargo.toml`	modify	Replace the `apps/augmented-books/` members with `solutions//apps//src-tauri`, explicit `solutions/augmented/apps/augmented-books/runners/sqlite/builder`, and `solutions//packages/rust/*`; additive, versions unchanged
`.moon/workspace.yml`	modify	Add `solutions//apps/` and `solutions//packages//*` to `projects.globs`; fix any moved-project `moon.yml` source paths
`apps/augmented-books/README.md`	modify	Update root-relative path references to the new `solutions/augmented/apps/augmented-books/` location
`apps/augmented-books/docs/code-quality.md`	modify	Fix path references broken by the two-level-deeper move
`apps/augmented-books/docs/architecture/project-structure.md`	modify	Fix path references broken by the two-level-deeper move
`docs/`	modify	`sdlc docs generate` + site build so project rosters/pages point at the new `solutions/augmented/...` sources (generated docs regenerated; site rebuilt)

Acceptance criteria

AC-1: All 5 apps and every surviving package live under solutions/augmented/ at the sub-paths above (apps/*, packages/ts/*, packages/rust/augmented-common), and the old apps/<app> / packages/ts/<pkg> / packages/rust/augmented-common paths no longer exist.
AC-2: Root package.json workspaces, Cargo.toml members, and .moon/workspace.yml projects.globs are updated to the solutions/* globs (plus the explicit builder-crate member).
AC-3: bun install completes clean and cargo metadata --locked exits 0 (paths changed, no version moved).
AC-4: moon query projects lists every moved project at its new solutions/augmented/... source.
AC-5: grep -rn finds no reference to the old apps/<app> or packages/ts/<pkg> (or packages/rust/augmented-common) paths for any moved item, outside this task doc and historical planning records.
AC-6: All 5 moved apps (augmented-books, augmented_dot_com, augmented_web, learn_web, vimit_prototype) still typecheck/build from their new solutions/augmented/apps/ location.
AC-7: the augmented-books README and its internal docs reference the new solutions/augmented/... paths; sdlc docs generate and the site build are clean; no living doc cites a stale apps/augmented-books/apps/learn_web/apps/augmented_web/apps/augmented_dot_com/apps/vimit_prototype or packages/ts/<moved-pkg> path (historical planning records exempt).

Out of scope

The per-package share/fold evaluation of the surviving packages (audit B-6V5U / B-UEE4) — future work, evaluated in place after the move.
Retiring the upstream source repo — that is T-B1VB.
Defining the solutions/ tier in D-0001 (that is T-1YSW) and deleting the clear-duplicate packages (that is T-J5DI).
Renaming any package (@augmented/*, @augment/*, augmented_books, etc. all keep their names).

Dependencies

T-1YSW — D-0001 must define the solutions/ tier this move is the reference application of.
T-J5DI — the clear-duplicate packages (render, frontmatter-validator, obsidian-bases-augment) must be gone first so this move never relocates dead weight.

Discovery context

This is the reference application of D-0001’s solutions/ tier: rather than the up-front convergence audit (T-JCML, superseded via PR #972), the augmented family moves into solutions/augmented/ for in-place evaluation by observed use.

Post-mortem

Captured by /sdlc:task-work on 2026-07-19. PR: pending.

Acceptance criteria coverage

AC-1: auto — all 5 apps and 10 packages resolve under solutions/augmented/; no old path survives on disk. Tree-level diff proves all 15 moved trees are byte-identical across the move apart from 12 deliberate moon.yml $schema depth fixes and the wave-3 doc edits.
AC-2: auto — root workspaces, Cargo.toml members, and .moon/workspace.yml projects.globs carry the solutions/* globs plus the explicit nested builder-crate member.
AC-3: auto — cargo metadata --locked exits 0 and Cargo.lock is byte-identical to pre-move; bun.lock delta is a balanced 258/258 path-only rewrite. No version moved.
AC-4: auto — moon query projects reports the same 50 project ids before and after, every moved project sourced at its new solutions/augmented/… path.
AC-5: auto — git grep over tracked files finds no stale path outside docs/planning/. The four remaining hits are correct: two deliberate !solutions/*/apps/… negations, and two six-ascent test paths that self-heal (verified to resolve to the new location).
AC-6: auto for 4 of 5 — nuxi prepare passes for augmented_web, learn_web, vimit_prototype; astro build for augmented_dot_com; vite build for augmented-books. Deferred: augmented-books’ vue-tsc --noEmit was deliberately not run locally (host-executor risk); vite build covers the path/alias resolution the move actually risks, but the type-level check needs CI.
AC-7: auto — augmented-books README and both internal docs repointed; sdlc docs generate and the site build both clean; no living doc cites a stale moved path.

What worked

Splitting into three waves (move → path fixes → docs), each leaving a clean committed tree, kept a 15-directory migration reviewable.
Tree-level comparison (git diff <old-rev>:<old-path> HEAD:<new-path>) is the right verification primitive for a move. Git’s rename-detection similarity scores are NOT — they showed ~100 files at 50–99% similarity that were actually byte-identical, mis-paired among many small similar files.
Cargo.lock byte-identity and an unchanged moon query projects id set are cheap, decisive proofs that a move was path-only.
Relative paths BETWEEN moved trees self-heal: both sides descended the same depth under a shared root, so a six-ascent traversal still lands correctly. Only references crossing OUT of the moved set broke.

Friction and automation gaps

start_task.ts ends with git reset --hard origin/main on the task branch, which destroys a stacked-PR base. This task had to sit on task/T-J5DI-…, so the parent rebased the sibling branch, force-pushed its PR, and re-pointed this branch by hand. The script should accept a --base <ref> (defaulting to origin/main) so a stacked run is a first-class flow.
lefthook.yml’s markdown-fmt exclude was pinned at apps/learn_web/** and silently stopped matching when the app moved, so rumdl reflowed 107 vendored book-content files on commit. The edits were SEMANTIC, not cosmetic — MD034 rewrote bare URLs as autolinks and MD025 demoted a book’s # Video Courses to ## Video Courses. A formatter that can rewrite app fixture data on a path change needs the exclude expressed as a moon/workspace project reference rather than a hand-written path glob.
The same class bit .gitignore: packages/ts/*/dist/ stopped covering eight moved packages, leaving build output committable. Nothing had landed yet, but the first moon run :build over the tier would have.
The Approach’s prescribed solutions/*/apps/* workspaces glob was wrong as written: it silently absorbed augmented-books and augmented_dot_com, which are their own Bun roots per D-0016/D-0018 and were never root members, pulling in 60 packages. Two ! negations were added. A membership-drift assertion (workspace member COUNT unchanged across a move) would have caught this without a human noticing the lockfile growth.
12 moon.yml $schema paths carried stale depths after the move. Harmless to moon, but editor validation silently died. A depth-aware $schema check belongs in the entities audit.
Verifying a move required the parent to re-derive truth after the implementer reported success: the wave-1 agent reported “zero content-changed files” and had restored only 21 of the 107 mangled files. The gap was found by tree-level diff, not by the agent’s own check. A sdlc gate move-integrity verb — assert every moved tree byte-identical modulo an allowlist — would make this mechanical instead of dependent on parent diligence.
B-6V5U and B-UEE4 are status: open/active backlog items citing pre-move paths as forward-looking work targets. They are exempt from AC-5’s docs/planning/ carve-out but will send whoever picks them up at dead paths. The exemption should distinguish closed historical records from open work items.
apps/learn_web’s dev script watches ../../packages/node/hierarchy/dist, but packages/node/ has never existed in this repo. Pre-existing and unrelated to the move; left as found.

Depends on

T-1YSW, T-J5DI

← Back to Tasks