# Mosaic Framework Constitution — Open Questions for the Human Operator These require an operator/maintainer decision before or during alpha implementation. Each lists the question, why it can't be auto-resolved, the design's provisional default, and the impact of the decision. `DESIGN.md` proceeds on the provisional defaults unless overridden. --- ## Q1 — License choice: MIT (provisional) vs Apache-2.0 vs AGPL-3.0 `DESIGN.md` §6 Phase 0 ships **MIT** per the synthesis (D8). This is irreversible-ish: the alpha tag fixes the IP status of all prior contributions, and changing the license after external forks exist is hard. MIT maximizes adoption; Apache-2.0 adds an explicit patent grant (relevant if Mosaic tooling touches patentable infra workflows); AGPL protects against closed SaaS forks of an agent framework. **Provisional: MIT.** Needs an explicit operator yes/no before the LICENSE file lands, because it is the one Phase-0 decision that cannot be cleanly reversed post-tag. ## Q2 — Is `mosaic init` mandatory before any launch, or is bare-launch a supported entrypoint? The design closes the headless-bootstrap hole by having `install.sh` run `mosaic-init --non-interactive`, and relies on `checkSoul()` for `mosaic ` launches. But **bare** `claude`/`codex`/`opencode` (bypassing `mosaic` entirely) remains a real path that gets base-only overlays, no `doctor` drift detection, and Tier-3 (weakest) injection. **Decision needed:** is bare launch a *first-class supported* entrypoint we guarantee gate-presence for, or a *best-effort, caveat-emptor* path documented as degraded? This sets how much engineering goes into the self-load fallback vs how loud the "use `mosaic `" warning is. ## Q3 — Non-interactive persona: fail-closed vs a sanctioned generic default? `DESIGN.md` §3.3 makes non-interactive init **fail-closed** on persona (error unless `--agent-name` given) to avoid silently shipping an agent named "Assistant" with the Jarvis role string (devex B2). This is safer but means **a fully-unattended fleet provision must supply `--agent-name`** in its automation. **Decision needed:** is fail-closed acceptable for the operator's actual Discord/ orchestrator/CI provisioning flows, or is a deliberately-chosen generic persona (e.g. "Mosaic Agent" with a neutral role) preferred for zero-touch deploys? If the latter, D6's rejection of generic-default persona must be formally amended. ## Q4 — Where does the framework `.woodpecker.yml` live, and is the CI authority Woodpecker? `verify-sanitized.sh`, the resident line-count ceiling, and the composer/migration tests must be wired **blocking**. There is **no `.woodpecker.yml`** at the framework package or monorepo root today (only project-template CI under `tools/quality/templates/`). **Decision needed:** monorepo-root pipeline vs a framework-package pipeline, and confirmation that Woodpecker (not GitHub Actions / Gitea Actions) is the gate authority for this package. This blocks Phase 1. ## Q5 — Overlay scope for the alpha: include `STANDARDS.local.md` and `policy/*.md`, or just SOUL/USER? `DESIGN.md` §3.2 ships `SOUL.local.md` + `USER.local.md` + `STANDARDS.local.md` and defers `policy/*.md` composition to v2. The §1.4 split makes `policy/` non-load-bearing for gates, so deferral is safe — but if the operator has near-term need for tighten-only operator policy beyond merge-authority, `policy/*.md` composition moves into the alpha. **Decision needed:** is deferring `policy/` composition acceptable for the alpha's actual use? ## Q6 — Migration handling of a user-edited root `AGENTS.md`: `.bak` + advisory vs interactive review? `DESIGN.md` §3.3 copies a user-edited v2 `AGENTS.md` to `AGENTS.md.pre-constitution.bak` and emits a non-blocking advisory — deliberately **no** interactive merge (would hang headless). This means a user who customized their root contract must **manually** re-apply intent into `CONSTITUTION.md`/overlays after upgrade. **Decision needed:** is "preserved-as-backup + advisory, manual re-apply" the accepted UX, or should `mosaic doctor` actively diff the `.bak` against the new structure and suggest where each edit should go? (The latter is more work; flagged because it changes the upgrade UX promise.) ## Q7 — OpenBrain URL default in the shipped hook `DESIGN.md` §2b changes `prevent-memory-write.sh` from the hardcoded `brain.woltje.com` to `${OPENBRAIN_URL:?...}` (fast-fail). That makes the memory hook **error** for any install that hasn't set `OPENBRAIN_URL`. **Decision needed:** is fast-fail correct (forces explicit config), or should the hook **soft-degrade** (skip the OpenBrain nudge, still block the write) when `OPENBRAIN_URL` is unset? Fast-fail is safer for the maintainer's fleet; soft-degrade is friendlier for first-time OSS adopters who don't run OpenBrain at all. ## Q8 — Is collapsing the two installers (`install.sh` + `file-adapter.ts`) into one in scope? `DESIGN.md` mitigates the dual-installer drift (contrarian R10) by requiring every change in **both** plus a shared fixture suite — but keeps two implementations. The more durable fix is to **collapse to one** (bash shells out to the node CLI, or vice versa). That is a larger refactor with its own risk. **Decision needed:** accept "two installers + shared fixtures" for the alpha (provisional), or fund the collapse now while the Constitution semantics are being added anyway? ## Q9 — Pi as an OSS-shippable runtime, or maintainer-internal? `runtime/pi/` and `adapters/pi.md` describe Pi as "the native Mosaic agent runtime" with no permission restrictions and a TypeScript extension. For a public alpha, **is Pi a runtime external adopters can actually install and run**, or is it maintainer-internal? This affects whether the cross-harness compliance matrix lists Pi as a supported public target (and whether the "Pi has no hook backstop / resident is its only enforcement" caveat is a public-facing constraint or an internal note). ## Q10 — `examples/personas/execution-partner.md`: ship the sanitized Jarvis persona, or a neutral one? The design preserves the worked Jarvis persona as a placeholdered example. The persona includes **PDA-friendly / accommodation-oriented** language (`defaults/SOUL.md:23`). **Decision needed:** is shipping that (sanitized, as one *example* among others) appropriate for a public package, or should the shipped example be a fully neutral persona with the accommodation-specific content kept entirely in the operator's private generated `SOUL.md`? This is a judgment call about how much of the original persona's character is appropriate as a public template.