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.