stack/docs/design/framework-constitution/OPEN-QUESTIONS.md

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 <harness> 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 <harness>" 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.