mosaicstack/stack
1
0
Fork 0
Code Issues 13 Pull Requests Actions Packages Projects Releases 11 Wiki Activity

install.sh does not seed TOOLS.md — breaks AGENTS.md mandatory load order #457

New Issue
Closed
opened 2026-04-12 01:56:29 +00:00 by jason.woltje · 1 comment
jason.woltje commented 2026-04-12 01:56:29 +00:00
Owner
Copy Link

Problem

~/.config/mosaic/TOOLS.md is never created during a bootstrap install, even though AGENTS.md (position 5 in the mandatory load order) declares it as required reading for every agent session. The installer explicitly lists TOOLS.md in PRESERVE_PATHS but then forgets to seed it from defaults/ — a pure oversight, not intentional.

As a second-order consequence, the mosaic claude / mosaic codex / mosaic opencode / mosaic pi adapter's "read these files in order" contract points at a file that does not exist. Jason's own install on a fresh 0.0.29 machine is currently broken this way.

Root cause

packages/mosaic/framework/install.sh lines 228-236:

DEFAULTS_DIR="$TARGET_DIR/defaults"
if [[ -d "$DEFAULTS_DIR" ]]; then
  for default_file in AGENTS.md STANDARDS.md; do    # ← missing TOOLS.md
    if [[ -f "$DEFAULTS_DIR/$default_file" ]] && [[ ! -f "$TARGET_DIR/$default_file" ]]; then
      cp "$DEFAULTS_DIR/$default_file" "$TARGET_DIR/$default_file"
      ok "Seeded $default_file from defaults"
    fi
  done
fi

Secondary issues found during investigation

  1. packages/mosaic/src/config/file-adapter.ts syncFramework is too greedy. It iterates every file under framework/defaults/ and copies any that don't exist — which would silently seed the Jarvis-flavored defaults/SOUL.md, placeholder defaults/USER.md, and internal AUDIT-*.md / README.md into the user's mosaic home before the wizard's own identity stages ever run. The fix restricts seeding to an explicit whitelist: AGENTS.md, STANDARDS.md, TOOLS.md.

  2. packages/mosaic/framework/templates/TOOLS.md.template is stale. It still references ~/.config/mosaic/rails/git/... and ~/.config/mosaic/rails/codex/.... The rails/ tree was renamed to tools/ in the v1 → v2 framework migration — so any user who did run mosaic init would end up with a TOOLS.md that points to non-existent paths. The fix replaces rails/ with tools/ in the template.

  3. preservePaths drift between bash and TS. install.sh preserves AGENTS.md STANDARDS.md SOUL.md USER.md TOOLS.md memory sources credentials on upgrade; file-adapter.ts was only preserving SOUL.md USER.md TOOLS.md memory. The fix brings the TS list into agreement with the bash list so the two install paths have identical upgrade semantics.

Fix

  • packages/mosaic/framework/install.sh — extend the explicit seed loop to AGENTS.md STANDARDS.md TOOLS.md.
  • packages/mosaic/src/config/file-adapter.ts — replace the greedy readdirSync loop with an exported DEFAULT_SEED_FILES whitelist and align preservePaths with the bash PRESERVE_PATHS.
  • packages/mosaic/framework/templates/TOOLS.md.template — rails/ → tools/.
  • packages/mosaic/src/config/file-adapter.test.ts (new) — 5 regression tests asserting the whitelist, the non-seeding of SOUL.md/USER.md/README.md/AUDIT-*.md, the preservation of existing user contract files under keep mode (including AGENTS.md), and no-op behavior when defaults/ is missing.

Affected version

@mosaicstack/mosaic 0.0.29 (current). Ships in 0.0.30.

## Problem `~/.config/mosaic/TOOLS.md` is never created during a bootstrap install, even though `AGENTS.md` (position 5 in the mandatory load order) declares it as required reading for every agent session. The installer explicitly lists TOOLS.md in `PRESERVE_PATHS` but then forgets to seed it from `defaults/` — a pure oversight, not intentional. As a second-order consequence, the `mosaic claude` / `mosaic codex` / `mosaic opencode` / `mosaic pi` adapter's "read these files in order" contract points at a file that does not exist. Jason's own install on a fresh 0.0.29 machine is currently broken this way. ## Root cause `packages/mosaic/framework/install.sh` lines 228-236: ```bash DEFAULTS_DIR="$TARGET_DIR/defaults" if [[ -d "$DEFAULTS_DIR" ]]; then for default_file in AGENTS.md STANDARDS.md; do # ← missing TOOLS.md if [[ -f "$DEFAULTS_DIR/$default_file" ]] && [[ ! -f "$TARGET_DIR/$default_file" ]]; then cp "$DEFAULTS_DIR/$default_file" "$TARGET_DIR/$default_file" ok "Seeded $default_file from defaults" fi done fi ``` ## Secondary issues found during investigation 1. **`packages/mosaic/src/config/file-adapter.ts` `syncFramework` is too greedy.** It iterates *every* file under `framework/defaults/` and copies any that don't exist — which would silently seed the Jarvis-flavored `defaults/SOUL.md`, placeholder `defaults/USER.md`, and internal `AUDIT-*.md` / `README.md` into the user's mosaic home before the wizard's own identity stages ever run. The fix restricts seeding to an explicit whitelist: `AGENTS.md`, `STANDARDS.md`, `TOOLS.md`. 2. **`packages/mosaic/framework/templates/TOOLS.md.template` is stale.** It still references `~/.config/mosaic/rails/git/...` and `~/.config/mosaic/rails/codex/...`. The `rails/` tree was renamed to `tools/` in the v1 → v2 framework migration — so any user who *did* run `mosaic init` would end up with a `TOOLS.md` that points to non-existent paths. The fix replaces `rails/` with `tools/` in the template. 3. **`preservePaths` drift between bash and TS.** `install.sh` preserves `AGENTS.md STANDARDS.md SOUL.md USER.md TOOLS.md memory sources credentials` on upgrade; `file-adapter.ts` was only preserving `SOUL.md USER.md TOOLS.md memory`. The fix brings the TS list into agreement with the bash list so the two install paths have identical upgrade semantics. ## Fix - `packages/mosaic/framework/install.sh` — extend the explicit seed loop to `AGENTS.md STANDARDS.md TOOLS.md`. - `packages/mosaic/src/config/file-adapter.ts` — replace the greedy `readdirSync` loop with an exported `DEFAULT_SEED_FILES` whitelist and align `preservePaths` with the bash `PRESERVE_PATHS`. - `packages/mosaic/framework/templates/TOOLS.md.template` — `rails/` → `tools/`. - `packages/mosaic/src/config/file-adapter.test.ts` (new) — 5 regression tests asserting the whitelist, the non-seeding of `SOUL.md`/`USER.md`/`README.md`/`AUDIT-*.md`, the preservation of existing user contract files under `keep` mode (including `AGENTS.md`), and no-op behavior when `defaults/` is missing. ## Affected version `@mosaicstack/mosaic` 0.0.29 (current). Ships in 0.0.30.
jason.woltje commented 2026-04-12 02:02:45 +00:00
Author
Owner
Copy Link

Fixed in PR #458, merged as c3f810bb on main. Framework installer now seeds ~/.config/mosaic/TOOLS.md from defaults/TOOLS.md on first install, the TS wizard's syncFramework uses an explicit whitelist, preservePaths are aligned between bash and TS, and the stale rails/ references in TOOLS.md.template are replaced with tools/. Ships in @mosaicstack/mosaic 0.0.30.

Fixed in PR #458, merged as `c3f810bb` on main. Framework installer now seeds `~/.config/mosaic/TOOLS.md` from `defaults/TOOLS.md` on first install, the TS wizard's `syncFramework` uses an explicit whitelist, `preservePaths` are aligned between bash and TS, and the stale `rails/` references in `TOOLS.md.template` are replaced with `tools/`. Ships in `@mosaicstack/mosaic` 0.0.30.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
No items
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
jason.woltje
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: mosaicstack/stack#457
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?