BOHICA-LABS / BOHICA-LABS/vsdd-factory

bug(onboarding): /onboard-observability creates .factory/logs/ in a plain dir, blocking later /factory-health worktree mount

Open
#203 2 comments 0 reactions 0 assignees View on GitHub
Dominant language
Rust
Stars
2
Forks
1
Avg merge
6h 43m
Merged PRs (30d)
29

Description

## Summary

`/vsdd-factory:onboard-observability` and `/vsdd-factory:factory-health` have a hard ordering dependency that neither skill enforces or documents. Running onboard-observability first on a fresh project puts the project in a state that factory-health cannot auto-repair without destructive operations on user data.

## Repro (vsdd-factory@1.0.0-rc.21)

Fresh project, no `.factory/`, no `factory-artifacts` orphan branch.

1. Invoke `/vsdd-factory:onboard-observability`
2. The skill calls `factory-obs register` which (transitively, via the running dispatcher hook) creates `.factory/logs/dispatcher-internal-2026-06-23.jsonl` inside a **plain directory** `.factory/`.
3. Invoke `/vsdd-factory:factory-health`
4. The skill's step 2 tries `git worktree add .factory factory-artifacts`, which requires `.factory/` to be empty or absent. It is not — it contains live dispatcher logs.

The factory-health skill has no branch for "plain `.factory/` directory containing only dispatcher logs" — its only options are "missing → create" and "mounted → check branch." The result is a stuck state where the operator must manually preserve logs, remove the dir, then mount.

## Why this is a problem

Onboarding observability is the **first** thing a new factory project does (and is encouraged in the onboard-observability skill's "When to use" section: "Brand new project that just had the vsdd-factory plugin installed"). Factory-health is the **prerequisite** for the rest of the pipeline. Today these two skills race and the documented first-time-use sequence fails.

## Proposed fix (pick one or compose)

### Option A: ordering — onboard-observability requires factory-health first

`/vsdd-factory:onboard-observability` should detect missing `factory-artifacts` worktree and either:
- Refuse with a clear "run /vsdd-factory:factory-health first" message, or
- Invoke factory-health implicitly before proceeding.

### Option B: factory-obs register defers log creation

`factory-obs register` should only register the project's path in the watch list. It should **not** trigger the dispatcher to start writing to `.factory/logs/` until `.factory/` is confirmed to be a `factory-artifacts` git worktree. The dispatcher could resolve `.factory/` via `git worktree list` rather than path-only.

### Option C: factory-health preserves pre-existing `.factory/logs/`

`/vsdd-factory:factory-health` step 2 ("Worktree is mounted") should detect a plain `.factory/` directory containing only `logs/` (or any non-tracked content), preserve it aside, mount the worktree, then restore `logs/` into the new worktree. Today the skill has no recovery branch for this case.

## Acceptance criteria

- [ ] On a fresh project, the sequence `/vsdd-factory:onboard-observability` → `/vsdd-factory:factory-health` (or the reverse) completes without manual intervention.
- [ ] `factory-obs register` does not create state inside `.factory/` until the worktree is confirmed (or factory-health has run).
- [ ] If a plain `.factory/` directory exists with content, factory-health preserves and restores that content cleanly.
- [ ] Both skills' "When to use" / "Prerequisites" sections cross-reference each other.

## Found during

First-time onboarding of `switchboard-blue` (Go project, develop branch) on 2026-06-23 with `vsdd-factory@1.0.0-rc.21`. The user invoked `/onboard-observability` then `/factory-health` in immediate succession. The latter could not auto-repair the dispatcher-logs-in-plain-dir state created by the former.

## Related

- #130 (closed) — recursive `.factory/.factory/logs/` shadow when dispatcher cwd is inside `.factory/`. The shadow case is fixed; this is a different scenario (no shadow, just a plain `.factory/` predating the worktree).

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.