mosaicstack/stack

Fork 1

Files

T

fred 4b448109dd

ci/woodpecker/pr/ci Pipeline was successful

Details

docs/prd: address independent review findings 1-10 (fidelity, A1 record class + carve-out, roadmap completeness)

2026-08-25 23:20:40 -05:00

86 KiB

Raw Blame History

kind, status, source_of_truth

kind	status	source_of_truth
spec	active	true

PRD: Mosaic Stack — North Star

This document is the product source of truth for Mosaic Stack.

Part I defines the product north star. It is written from the ratified decision set D1–D14 (operator decision session, 2026-08-25; decision owner Jason Woltje). Each section cites the decisions it implements.
Part II preserves the active workstream contracts unchanged. Open issues bind to them; this rewrite does not alter a single normative word in them.
The previous v0.1.0 beta PRD body is archived verbatim at docs/archive/PRD-v0.1.md and is no longer authority.
The delivery roadmap lives in docs/ROADMAP.md. Per D11, every planned phase appears there from day one, even as a placeholder.

Metadata

Owner / decision authority: Jason Woltje
Status: active (supersedes the v0.1.0 PRD as product authority)
Date: 2026-08-26
Decision registry: D1–D14, recorded in Part I §12
SSOT rule: this repository's docs/ tree is the product source of truth (D5). Estate brains hold operational records, not product canon; only product-relevant material migrates here (D6).

Part I — Product north star

1. What Mosaic Stack is (D1)

Mosaic Stack is an open-source, AI-first platform for people who want a self-hosted environment for agentic management and a life operating system. It serves personal, business, and employee needs from one deployment, and the work is offered freely.

"AI-first" means agents are first-class operators of the system, not a bolted-on chat box: the platform exists to let humans direct fleets of agents over their projects, tasks, communications, and infrastructure, with the same tools and the same guarantees whether a human or an agent is acting.

2. Who it is for (D1, D9)

The operator of a deployment is its user. Mosaic Stack is not a hosted business: running the system as a service for external customers is outside the north star. Multi-tenancy exists WITHIN a deployment so that one operator can separate their world — for example, several LLCs plus a personal domain — while every deployment is self-hosted by its own operator.

"Company" in the hierarchy is organizational separation for one operator's world, not a customer account.

3. Deployment modes (D3)

Two modes, chosen at install time:

	Standalone / personal	Enterprise
Brains	one mosaic-brain (system + user files)	system brain for config + one brain per user
User-data isolation	single user	no user-data leakage between users; sharing is opt-in
Secrets	OpenBao/Vault or flat files	OpenBao/Vault REQUIRED
Conversion	Standalone → Enterprise, one-way	terminal state

Brains are configurable as external git repositories (recommended, not required); git tracking is always on locally.

Federation (connecting deployments: system-level config, assigned users, rights and data-access control, trusts with boundaries, exfiltration monitoring) is intentionally not fully designed. It is deferred, appears on the roadmap as a placeholder phase per D11, and nothing in v1 may foreclose it.

4. Structure and tenancy (D2, D9, D13)

The hierarchy:

company/organization  (N per deployment)
└─ estate             (each in exactly one company)
   └─ project         (each in exactly one estate)
      └─ workspace    (project-specific; carries the Kanban)

Rules:

Users can create N companies, N estates, N projects.
Tasks bubble UP the hierarchy so whole-system status is visible at every level. Bubble-up is read-only aggregation, never a cross-workspace write.
Granular RBAC: admins restrict access per company, estate, and project; grants are evaluated down the chain. Assets are transferable subject to the structure.
workspace_id remains the hard mechanical isolation unit exactly as ratified in docs/requirements/native-kanban-sot.md (#751): PostgreSQL sole writable SOT, cross-workspace relationships rejected, fail-closed mutations. The hierarchy is parent structure ABOVE workspaces, used for RBAC evaluation and read-only roll-ups. The kanban SOT carries this as Amendment A1, added by reviewed PR — an amendment, not a rewrite (D13).

5. Identity (D10)

Built-in auth (better-auth) is the account system of record. Authentik and other external IdPs federate in via OIDC as login methods; they never become the system of record. Perimeter shims (forward-auth in front of a web host) are deployment workarounds, not the design.

6. Onboarding (D4)

Onboarding is a wizard that differs by mode, is re-runnable (no lock-in), and is extensible — new wizards attach as tabs.

Standalone flow captures: system and company name; component choices (Mosaic Comms/Matrix vs external; Mosaic SSO/Authentik vs external; Mosaic DB/PostgreSQL vs external; vector DB); the initial user (email/password/name/SSO); comms setup (Matrix/Discord/Slack); agent enrollment (harness choice and install, OAuth or API-key login, multi-account, model choice with recommendation, agent name and persona, account assignment, optional comms auto-enroll); a user onboarding profile (disabilities including ADHD/autism/PDA/vision, professional background, education, desired agent communication style, optional voice-matching interview, family/pets/friends/ hobbies/likes-dislikes); email and drive connectors (Gmail/IMAP, Google Drive/OneDrive/Dropbox) with granular agentic-access consent; SSO/OIDC configuration; an initial estate, an initial project, and seeded example data.

Enterprise uses the same skeleton with personal data optional; the focus moves to business structure, org chart, RBAC, M365 and external systems, immediate OIDC, SSO prominent.

Profile answers feed USER.md and/or the user's data store subject to the custody rule in §7.

7. Data custody (D6, D14)

Sensitive profile categories (disabilities, family, communication style, and similar) live in the user's own brain ONLY. PostgreSQL holds structural data, consent records, and pointers — never the content. "User data does not leak" is enforced by architecture, not policy (D14).
Standalone (one user, one brain) may keep the same split — D14 makes it optional in Standalone, not required. Keeping it is the recommended default because it preserves forward-compatibility with the one-way Enterprise conversion (D3).
Estate brains hold operational records. Only product-relevant material migrates into this repository's docs; operational records stay in their brains and are linked (D6).

8. Architecture gate — the webUI sits OVER official tooling (D8, D12)

HARD RULE: every webUI operation goes through the Gateway API backed by the same official framework tooling the CLI uses. The CLI remains the primary execution method; the webUI uses the tools to operate and configure the system. The webUI never bypasses tooling to reach the database or filesystem directly.

Consequence for planning: when a desired webUI operation has no backing tool, the gap is scored "blocked on tooling" and the tool is built first. The product baseline therefore always includes all three D8 inputs: the tool inventory (what exists and what is missing), the webUI→tool mapping, and the measured current state of the next branch.

9. v1 slice (D11)

v1 is deliberately small:

Standalone onboarding wizard — system/company name, component choices, initial user, initial estate + project, seeded examples, re-runnable.
Hierarchy core — company → estate → project → workspace → kanban, with read-only task bubble-up.
Basic RBAC on the hierarchy.
Minimal agent enrollment — one harness, API key, name/persona.

Deferred beyond v1: connectors, comms integrations, voice-matching, M365, Enterprise conversion, federation. Every deferred item appears in docs/ROADMAP.md per the D11 rule: nothing exists only in heads.

10. Relationship to the fleet north star

docs/fleet/NORTH_STAR.md (generated from docs/fleet/NORTH_STAR.yaml) is the delivery-fleet north star: how the agent fleet that builds and operates the system should run (NS-1..NS-10, workstreams A–L). This PRD is the product north star. They are not competitors: the fleet north star is subordinate product-wise — its workstream J ("Web control plane") is one consumer of this PRD's D8/D12 gate — and this PRD does not redefine fleet invariants. The subordination rule is ratified in the frozen audit-input baseline (T2 operator freeze, 2026-08-25: "the PRD must cite and subordinate it, never fork it"). A change that would put the two in conflict must amend one of them explicitly, never fork a third document (drafting addition — see §12.1).

11. Explicit non-goals

Hosted/SaaS operation for external customers (D9).
A webUI that writes to the database or filesystem around the tooling (D12).
A second writable task store beside PostgreSQL (native-kanban-sot invariants).
Fully-designed federation in v1 (D3 — roadmap placeholder only).

12. Decision registry

ID	Decision (short form)
D1	Open-source, AI-first, self-hosted platform for agentic management + life OS
D2	Hierarchy company→estate→project→workspace→kanban; bubble-up; granular RBAC
D3	Standalone vs Enterprise; one-way conversion; per-user brains + Vault required in Enterprise; federation deferred
D4	Re-runnable, extensible, per-mode onboarding wizards
D5	North star = this rewrite of docs/PRD.md; stack docs/ = product SSOT
D6	Only product-relevant material migrates from brains; operational records stay and link
D7	Spec-inventory sweep launched immediately (executed; INPUTS baseline frozen by operator ruling T2, 2026-08-25)
D8	webUI sits over official framework tooling; CLI primary
D9	Not a hosted business; company = organizational separation for one operator
D10	better-auth is the account system of record; external IdPs via OIDC
D11	Small v1 slice; ALL phases on the documented roadmap from day one
D12	HARD RULE: webUI never bypasses tooling; missing tool ⇒ build the tool first
D13	workspace_id stays the hard isolation unit; hierarchy is parent structure above; kanban SOT amended, not rewritten
D14	Sensitive profile data in the user's own brain only; postgres holds structure/consent/pointers

The full decision texts are recorded in the operator decision log (USC estate brain, webui-audit lane, GRILL.md).

12.1 Drafting additions beyond D1–D14

Independent review of this rewrite identified rules in this document that are not present in the D1–D14 record or the frozen T2 baseline. They are listed here so their ratification is explicit: approval of the PR that introduces this document, by the decision owner, ratifies them. If any is rejected it is removed, not silently kept.

Federation forward-compatibility gate: "nothing in v1 may foreclose federation" (§3), and scoping federation later requires its own PRD plus threat model (ROADMAP P5). D3 defers federation; these protective gates are additions.
North-star amendment rule: a product/fleet north-star conflict must be resolved by amending one of the two documents explicitly, never by forking a third (§10). The subordination itself is T2-ratified; this amendment procedure is an addition.

Part II — Active workstream contracts (preserved unchanged)

The sections below are normative, in-flight workstream contracts carried over verbatim from the previous revision of this file. Open issues bind to them. This rewrite moved no text and changed no requirement in them; they are governed by their own issues and review gates, and they graduate out of this file individually when their workstreams close.

Current addendum: #1194 — Installed framework-tool drift detection

Compare the framework tools shipped with the executing Mosaic package against the deployed $MOSAIC_HOME/tools tree by content hash.
Treat every shipped tools/** file as framework-owned/required according to framework-manifest.txt, while excluding the explicit operator-owned credential carve-out and preserving installed-only operator/unknown files.
Distinguish and count IN_SYNC, STALE, NOT_INSTALLED, and installed-only classifications; fail non-zero when shipped tools are stale or absent and refuse self-comparison that would make drift unobservable.
Surface the observational check through mosaic doctor; do not refresh files, restart seats, or mutate live tooling.
Document identity/messaging/gate behavior changes in the current stale set, the reviewed quiet-window keep-mode refresh command, and post-refresh probes against the installed path.
Prove by construction that a stale and missing deployed tool are detected; that regression must fail before this checker exists.

Compaction Refresh Trust Lifecycle (M1, #827–#830)

Problem and objective

Context compaction, session replacement, and same-PID runtime reloads can leave a previously VERIFIED runtime lease attached to stale directives. M1 must revoke that authority mechanically for Claude (including Claudex) and Pi without trusting caller-asserted identity or forking the external broker state machine.

Requirements

CR-REQ-01: Claude PreCompact and SessionStart with matcher compact, plus Pi session_before_compact and the first post-session_compact context, SHALL independently revoke the active broker lease.
CR-REQ-02: Runtime generation increases—including same-PID Pi reload/new/resume/fork and Claude resume/clear—SHALL monotonically replace the prior broker incarnation and inherit no VERIFIED lease.
CR-REQ-03: A fired observer that cannot confirm broker revocation SHALL fail closed through lifecycle cancellation, a private local generation fence, and/or a runtime-local tool latch. The existing all-tools broker gate remains authoritative.
CR-REQ-04: The lease TTL SHALL remain monotonic and capped at 300 seconds. If both observers are missed, within-TTL consequential actions remain allowed and after-TTL actions are denied. This named bounded residual stale window SHALL be documented without claiming a mutator-action bound inside the window.
CR-REQ-05: Hook descendants SHALL use the broker-minted session and owner-only current-generation state inherited from register-before-exec. Caller-minted sessions and parallel lease state machines remain forbidden.

Acceptance criteria

AC-CR-01: Real-socket tests prove each Claude observer revokes, Pi lifecycle tests prove both observer paths, and Claudex isolated settings preserve and install the mandatory hooks.
AC-CR-02: A same-PID generation test proves the old generation is stale and the replacement generation is UNVERIFIED across reload/resume/fork-equivalent lifecycle events.
AC-CR-03: RED-first T12b/T30 evidence explicitly reports dual-hook miss within TTL as ALLOWED and after TTL as DENIED.
AC-CR-04: Attributable executable coverage is at least 85%, the full repository suite is green on deterministic main, and independent code/security review completes before merge.

Pi Persistent Goal Loop (#1150)

Problem and objective

A Pi agent can stop after a plausible-looking answer even when the operator's broader objective is not complete, and ordinary compaction can weaken or omit the original objective. Mosaic needs an optional, operator-controlled goal loop that keeps a Pi session oriented, checks progress at native lifecycle boundaries, and resumes work until completion is verified or a bounded safety state is reached.

The objective is a Mosaic-owned Pi extension deployed from the framework into ~/.config/mosaic/runtime/pi/. It must not install into or depend on ~/.pi/agent/extensions/.

Scope

In scope

PGL-REQ-01: The framework SHALL ship a dedicated Pi goal extension under packages/mosaic/framework/runtime/pi/, seed it under $MOSAIC_HOME/runtime/pi/, and make mosaic pi load it alongside the core Mosaic extension when present.
PGL-REQ-02: /goal SHALL support setting a goal plus status, pause, resume, cancel, and help operations without silently replacing an active goal.
PGL-REQ-03: Active branch-specific goal state SHALL be persisted in Pi custom session entries, restored on session start and tree navigation, and never rely on a compaction summary as its source of truth.
PGL-REQ-04: A hidden goal contract SHALL be injected through Pi's context event before every model request so it remains effective across tool turns, retries, and post-compaction requests.
PGL-REQ-05: The harness SHALL inspect every turn_end and successful session_compact event. A structured terminating goal-report tool SHALL capture continue, evidence-bearing achieved, or blocked status without requiring a redundant model turn.
PGL-REQ-06: An achievement claim SHALL remain provisional until a second consecutive evidence-bearing verification report. Any continuation report or successful compaction during verification SHALL reset the verification sequence.
PGL-REQ-07: Continuation SHALL be initiated at safe lifecycle boundaries, primarily agent_settled; manual compaction and restored active sessions may schedule a deferred idle continuation without re-entering compaction handlers.
PGL-REQ-08: The loop SHALL have operator cancellation plus bounded turn and repeated-no-progress limits. Exhausted or blocked goals pause rather than continuing indefinitely.
PGL-REQ-09: Framework installation and update SHALL preserve normal manifest ownership: the goal extension is framework-owned under runtime/**, while no goal extension or configuration asset is created or modified under the operator's main Pi configuration. Pi remains the owner of its native session files used by appendEntry().

Out of scope

A mathematical guarantee that an arbitrary natural-language goal is semantically complete.
Automatically executing user-supplied shell predicates or accepting executable validation code in /goal arguments.
Restarting Pi after process, host, or supervisor failure; the existing Mosaic fleet/runtime supervisor owns process durability.
Gateway, database, web UI, Discord, or cross-harness goal orchestration in this slice.

User and stakeholder requirements

An operator can start a goal from Pi and see its current phase, evidence, limits, and latest report.
The agent remains oriented after each turn and compaction until verified, paused, blocked, exhausted, or cancelled.
Local testing uses a file under ~/.config/mosaic/runtime/pi/; the feature never writes an extension asset to ~/.pi/agent/extensions/.
Framework updates deploy the same reviewed extension source through Mosaic's existing manifest sync path.

Non-functional requirements

Safety: bounded continuation, explicit cancellation, no arbitrary command execution, and no completion without non-empty reported evidence.
Reliability: serialized continuation scheduling, branch-aware restoration, compaction-safe context injection, and stale-timer cancellation on session shutdown.
Performance: no extra nested judge-model request on every turn; structured reporting uses the active agent's final terminating tool call.
Observability: Pi status/notifications expose phase and bounded counters without recording credentials or hidden model reasoning.
Maintainability: the state machine is deterministic and behavior-tested independently from Pi provider/network access.

Acceptance criteria

AC-PGL-01: A framework-sync fixture installs the extension at $MOSAIC_HOME/runtime/pi/goal-extension.ts, and launcher tests prove both Mosaic Pi extensions are emitted in deterministic order while absent optional files remain backward-compatible.
AC-PGL-02: Command tests prove set/status/pause/resume/cancel behavior, active-goal replacement refusal, and bounded input handling.
AC-PGL-03: Lifecycle tests prove every turn is recorded, active context is injected on every request, two evidence-bearing achievement reports are required, and agent_settled continues an unmet goal without duplicate scheduling.
AC-PGL-04: Compaction and restoration tests prove goal state survives, verification is reset and rechecked after compaction, manual compaction continuation is deferred until idle, and tree/session branch state is reconstructed correctly.
AC-PGL-05: Limit tests prove max-turn and repeated-no-progress exhaustion stop autonomous continuation, while pause/cancel/blocked states do not restart.
AC-PGL-06: Focused tests, package typecheck/lint/test, repository quality gates, a local Pi load smoke test from ~/.config/mosaic/runtime/pi/, independent review, and terminal-green CI pass before issue #1150 closes.

Constraints, risks, and assumptions

Dependency: Pi's extension API must continue to provide registerCommand, registerTool, context, turn_end, agent_settled, session_compact, session custom entries, and terminating tool results.
Risk: the working agent can overstate completion. Mitigation: structured evidence, a mandatory second verification pass, explicit semantic limitations, and operator-visible reports.
Risk: an impossible goal can consume unbounded resources. Mitigation: hard turn/no-progress bounds and paused terminal states.
Risk: automatic continuation can race compaction or session replacement. Mitigation: drive from agent_settled, defer idle restarts, generation-check timers, and clear timers on shutdown.
ASSUMPTION: Two consecutive evidence-bearing reports are the initial local verification policy; rationale: it provides a real recheck without doubling every turn's model cost. Future policy may add independent or deterministic validators.
ASSUMPTION: Default limits are 40 turns and 6 repeated no-progress reports, configurable only by bounded Mosaic environment settings; rationale: useful persistence with a finite autonomous budget.
ASSUMPTION: Documentation remains canonical in-repo for this slice; no external docs publication is requested.

Testing and delivery intent

Use TDD for the deterministic controller and lifecycle invariants. Test with fake Pi lifecycle objects first, then run a local load/smoke test from the deployed Mosaic path. Deliver source, tests, launcher wiring, framework/runtime documentation, user/developer guides, and sitemap updates in one reviewed squash PR to main with terminal-green CI.

Fleet Declarative Configuration Management Workstream (FCM, #758)

Problem and objective

The local Mosaic fleet has a roster, generated agent environment files, user-systemd units, tmux sessions, heartbeat files, examples, profiles, and separate gateway-backed agent records. These planes have drifted and are not one safe operator lifecycle. The objective is one local fleet roster as the desired-state SSOT, with generated environment, systemd, tmux, and heartbeat artifacts as rebuildable projections; it does not merge the local fleet control plane with the gateway-backed agent catalog.

Normative requirements

ID	Requirement
`FCM-REQ-01`	The roster SHALL be the sole writable desired-state source for local fleet membership, launch policy, and persisted lifecycle target. Generated environment files, systemd enablement, tmux sessions, and heartbeat state SHALL be non-authoritative projections.
`FCM-REQ-02`	The implementation SHALL provide one executable structural contract for YAML/JSON input and one shared semantic validator. Roster load, profile validation, provision, migration, and apply SHALL reuse the existing baseline-plus-`roles.local` profile/persona resolver; a parallel role resolver is forbidden.
`FCM-REQ-03`	The local fleet CLI SHALL expose documented programmatic validate, show, plan, apply/reconcile, create, inspect, update, delete, start, stop, restart, status, verify, and doctor operations with stable JSON and exit-code behavior. Existing `fleet add/remove` compatibility aliases may remain during the stated deprecation window.
`FCM-REQ-04`	A fresh create SHALL persist `enabled:true` and `desired_state:stopped` unless an explicit persisted start is requested. The model SHALL distinguish enabled state, persisted desired state, and observed state. Migration, apply, reboot, and rollback SHALL not start an agent that was observed stopped before cutover.
`FCM-REQ-05`	The launch chain SHALL consume deterministic, digest-stamped generated input only. Optional local overrides SHALL be parsed as strict data, may not shadow authoritative generated keys, and may not contain arbitrary commands, credential values, channels, or unknown `MOSAIC_AGENT_*` keys. Forbidden legacy keys, including `MOSAIC_AGENT_COMMAND`, SHALL be privately quarantined before launch and reported only by key name and content hash.
`FCM-REQ-06`	Mutations and apply SHALL validate before mutation, use an expected generation/lock, write projections atomically, produce a deterministic plan, and emit recovery information on partial failure. Reconciliation SHALL act only on local, enabled, roster-owned projections and SHALL not kill unmanaged tmux sessions by fuzzy name.
`FCM-REQ-07`	Canonical required classes are `code`, `review`, `validator`, `orchestrator`, `team-leader`, `enhancer`, and `interaction`. `validator` issues an independent final certificate but has no merge authority; `merge-gate` remains sole approve-to-land/merge authority. Team-leader capacity is bounded by an orchestrator-issued lease, and interaction is request/status only. Tess and Ultron are configurable instance/display names, not required machine identities.
`FCM-REQ-08`	v1 migration SHALL be field-complete, reversible, and explicit about aliases, unresolved classes, lifecycle inference, generated-file regeneration, local override quarantine, schema-only remote/connector fields, and rollback. Every shipped example, profile, and service preset SHALL be migrated and executable, retained as an explicitly versioned v1 fixture, or retired with a replacement and deprecation note.
`FCM-REQ-09`	M1–M5 SHALL remain local tmux/systemd control-plane work. Remote/SSH reconciliation, connector mutation, secret references, arbitrary command/channel overrides, gateway/API convergence, and UI configuration storage are excluded and require a separate PRD/threat model.
`FCM-REQ-10`	Documentation and examples are delivery gates. The M0 checklist at docs/fleet/FLEET-CONFIG-DOCS-IA-CHECKLIST.md and the baseline disposition inventory at docs/fleet/LEGACY-EXAMPLE-PROFILE-DISPOSITION-INVENTORY.md SHALL be maintained as acceptance evidence.

Acceptance criteria

AC-FCM-01: A valid local v2 roster can be parsed from YAML or JSON, validated structurally and semantically through the shared resolver, and rendered canonically; invalid fields, duplicate names, unresolved classes, unsupported runtime/model combinations, socket ambiguity, and incompatible options fail closed.
AC-FCM-02: plan reports deterministic desired-versus-observed differences for roster, generated environment, systemd enablement, tmux/session, heartbeat, installed-asset revision, and provable orphans without mutation; apply --check reports drift without mutation.
AC-FCM-03: Local create/update/delete is generation-guarded, atomic, idempotent, and safe by default; it permits supported runtime/model/harness/effort/workdir/role changes without direct editing of generated environment files and does not start a newly created agent unless explicitly persisted.
AC-FCM-04: The generated-env/local-override launch chain rejects generated-key shadowing, arbitrary command override, unknown keys, shell evaluation, and sensitive-value diagnostics before any agent starts; known-safe legacy input is regenerated or strictly relocated, and forbidden input is quarantined.
AC-FCM-05: Local lifecycle reconciliation implements the persisted/transient start-stop rules, exact default/named tmux socket targeting, systemd/tmux status, stale generated state, unmanaged-session reporting, and rollback without surprise restarts or fuzzy destructive targeting.
AC-FCM-06: A v1 roster migration previews field-by-field disposition, preserves observed stopped/running state, inventories rather than reconciles remote/schema-only entries, supports a canary and rollback, and classifies every shipped example, profile, and service preset according to the M0 inventory.
AC-FCM-07: Required role authority is validated: validator certificate is consumed but does not merge, merge-gate is the sole merge authority, team-leader leases do not change roster/credentials/authority, and interaction/Tess cannot claim orchestration or merge powers.
AC-FCM-08: Documentation, examples, migration, troubleshooting, operational recovery, package/update asset drift, schema/example/profile validation, independent code/security review, validator certificate, and terminal-green CI are complete before #758 closes.

M0 implementation gate

No source, schema, role, example, profile, systemd, or live-fleet change is authorized before M0 lands. M0 consists only of these normative requirements, the complete task DAG, the scoped documentation IA checklist, and the legacy example/profile disposition inventory. Subsequent cards are defined in docs/TASKS.md and must remain one card/one PR.

Fleet git identity launch propagation (#1043)

Problem and objective

A fleet seat can have a registered per-agent Git credential while its launched runtime process lacks MOSAIC_GIT_IDENTITY. The credential resolver then cannot select the seat identity reliably, which blocks repository operations on fail-closed estates and can fall through to an unrelated identity on estates where that refusal is not active. The objective is to make Git identity a deterministic, roster-derived part of the generated launch projection and prove it reaches the launched process.

Normative requirements

FGI-REQ-01: Every generated fleet agent projection SHALL declare MOSAIC_GIT_IDENTITY=<MOSAIC_AGENT_NAME>; a differing or unsafe identity SHALL fail closed before tmux launch.
FGI-REQ-02: The clean /usr/bin/env -i pane boundary SHALL pass every variable declared by the generated projection, including MOSAIC_GIT_IDENTITY, to the launched runtime process.
FGI-REQ-03: A behavioral integration test SHALL set-compare the complete generated projection against the launched process environment. Source-text/string-presence assertions are insufficient.
FGI-REQ-04: Verification SHALL include RED-first evidence and a delete-the-subject mutation that removes Git-identity pane propagation and makes the behavioral test fail.

Acceptance criteria

AC-FGI-01: A launched seat process contains every key/value pair declared by its generated environment projection, including the roster-derived Git identity.
AC-FGI-02: Missing, unsafe, or split Git identity is rejected before a tmux session is created.
AC-FGI-03: Focused launcher and generated-environment tests, repository quality gates, independent review, and the required RED/green/R7 evidence are recorded before push.

Framework shell assertion portability (#1098)

Problem and objective

The blocking framework-shell chain can report that a pane command omitted /usr/bin/env -i even when -i matched successfully. A short-circuiting grep -q under set -o pipefail may close its pipe after the match and cause an upstream producer to exit with SIGPIPE, turning a valid semantic result into a nonzero aggregate pipeline. The objective is to inspect the captured NUL-delimited argv directly and make failures carry the observed records needed for diagnosis.

Normative requirements

FSP-REQ-01: The pane-boundary test SHALL validate an adjacent /usr/bin/env, -i argv pair from the authoritative NUL-delimited tmux capture without a short-circuit pipeline whose upstream status can override a successful match.
FSP-REQ-02: Missing, reversed, or non-adjacent boundary tokens SHALL fail, while valid boundaries SHALL remain valid regardless of trailing argv size, pipe capacity, process scheduling, or host/CI utility implementation.
FSP-REQ-03: A failed boundary check SHALL print stable indexed, shell-escaped observed argv records before exiting nonzero; the fixture SHALL continue to contain generated non-secret launch data only.
FSP-REQ-04: Verification SHALL include RED-first large-payload evidence, negative token-order controls, the complete focused launcher suite, canonical Woodpecker CI, and independent review.

Acceptance criteria

AC-FSP-01: A large captured argv with adjacent /usr/bin/env, -i passes even when the former grep -q pipeline returns nonzero from an upstream SIGPIPE.
AC-FSP-02: Missing executable, missing flag, and detached/reversed flag fixtures return nonzero and emit the indexed observed argv.
AC-FSP-03: The focused suite passes on the development host and CI image, and the merged-main Woodpecker pipeline is terminal green before #1098 closes.

Exact Cross-Harness Fleet Communications Contract (#766)

Problem and objective

Fleet runtime contracts currently combine exact peer rows with generic operational metavariables and independently parsed roster data. Non-Claude harnesses can mistake those metavariables for values to infer, producing incorrect host, session, socket, or helper targets. The objective is one roster-resolved communications contract that every supported harness receives unchanged.

Normative requirements

FCOM-REQ-01: Fleet commands and runtime composition SHALL use one shared v1 roster structural resolver. A second lenient communications parser is forbidden.
FCOM-REQ-02: The composed contract SHALL render the local roster member's authoritative host, exact agent/session name, resolved tmux socket, exact helper path, and deterministic communications generation.
FCOM-REQ-03: Every known peer SHALL have one exact executable command. Same-host commands SHALL omit -H; cross-host commands SHALL use only that peer's explicit roster ssh target; the one supported fleet-wide named socket SHALL use -L with its exact value. A per-agent socket declaration must equal that fleet-wide value; unsupported independent sockets and missing cross-host SSH data SHALL fail closed.
FCOM-REQ-04: Operational fleet examples SHALL not contain unresolved host, session, socket, or helper-path metavariables. Agents SHALL select an exact rendered peer row and SHALL NOT infer, substitute, or fuzzy-match targeting values.
FCOM-REQ-05: An unknown local member or requested peer SHALL fail closed with exact-name discovery guidance. Runtime composition SHALL not silently omit a requested fleet member's communications contract.
FCOM-REQ-06: Claude Code, Codex, OpenCode, and Pi SHALL receive equivalent authoritative communications data through the common runtime composer.
FCOM-REQ-07: Tests SHALL prove the contract from framework-source TOOLS.md, through a fresh installed TOOLS.md, to final runtime composition and helper executability. User-owned installed TOOLS.md content SHALL remain preserved.
FCOM-REQ-08: Stale installed or active composed context SHALL be reported with deterministic generation/repair/relaunch guidance. Currency requires the expected source and installed contract marker/version plus bounded byte equality. The supported current-version repair SHALL run independently of package updates, preserve divergent TOOLS.md bytes in a digest-qualified no-clobber backup, restore a regular executable helper without following symlinks, and be idempotent. Detection and reporting SHALL NOT rewrite active context, restart a session, or mutate a live fleet.
FCOM-REQ-09: The shared resolver SHALL preserve and strictly validate every schema-supported v1 connector kind (tmux, discord, and matrix) from YAML and JSON. Every accepted snake/camel alias pair SHALL reject differing dual declarations and accept identical declarations. JSON roster fallback SHALL occur only when roster.yaml is absent; all other YAML access failures SHALL fail closed.
FCOM-REQ-10: The communications generation SHALL cover the complete canonical rendered semantic contract, including identity, role/class, resolved host/socket/helper, peer metadata, and exact commands. Installed helpers SHALL be validated with no-follow filesystem inspection as regular executable files. Keep-mode reseed and relaunch discovery SHALL preserve and support both YAML and JSON rosters.

Acceptance criteria

AC-FCOM-01: Contract fixtures contain no unresolved operational targeting metavariables; local identity contains exact host/session/socket/helper values.
AC-FCOM-02: Same-host, cross-host, named-socket, literal-default-socket, and missing-SSH tests prove exact targeting and fail-closed behavior.
AC-FCOM-03: Unknown identities and peers report known exact names plus an exact self-scoped discovery command; no fuzzy session selection is emitted.
AC-FCOM-04: Four-harness tests prove byte-equal authoritative communications sections.
AC-FCOM-05: Source, fresh-install, preserved-custom-install, stale-installed, composed-generation, helper executable, agent-send socket isolation, and exact-target tests pass.
AC-FCOM-06: Documentation defines non-mutating stale-context detection and operator-authorized, exact-agent relaunch; no implementation path performs automatic session mutation.
AC-FCOM-07: YAML and JSON fixtures cover every connector kind; all snake/camel aliases cover identical acceptance and conflicting rejection; non-ENOENT YAML failures do not fall back.
AC-FCOM-08: Missing, directory, symlink, and non-executable installed helpers fail closed. Explicit current-version repair proves partial-deletion recovery, digest-qualified backup collision safety, symlink-target safety, and repeated-run idempotence.
AC-FCOM-09: Markerless-equal and wrong-version source/installed contracts are stale, and a rendered role/class change produces a different communications generation.

KBN-101 Database Runtime/Migration Role Split (#771)

Problem and objective

PostgreSQL Gateway/storage currently uses one DATABASE_URL for runtime queries and migrations. That makes the deployed application identity an owner and prevents certification that KBN immutable event, artifact, checkpoint, and evidence relations reject runtime UPDATE/DELETE. KBN-101 freezes a least-privilege runtime/migration split before KBN-100 schema work.

Normative requirements

K101-REQ-01: DATABASE_URL SHALL be the non-owner PostgreSQL runtime connection and DATABASE_MIGRATION_URL SHALL be the migration-only owner/migrator connection. They are required respectively for runtime and the dedicated mosaic-db-migrator --run|--verify phase in standalone/federated; local PGlite is the explicit exception. The published @mosaicstack/db bin maps exactly mosaic-db-migrator to ./dist/cli.js, its image entrypoint is exactly mosaic-db-migrator, accepts no URL/SQL/schema/role argv, and returns stable sanitized exits. Every current/future PostgreSQL DDL entrypoint SHALL route to that runner or be denied, and SHALL reject DATABASE_URL-only execution before connection/DDL. Data migration may connect only after the runner prepares and verifies the PostgreSQL target, through dedicated non-DDL mosaic_data_importer and exactly --target-url-file /run/secrets/mosaic-migrate-target-url, its fixed paired authenticated provider-version file /run/secrets/mosaic-migrate-target-version, plus --target-attestation-file /run/mosaic-attestations/migrate-target.v1.json. KBN-101-05 obtains URL key url and version only from the same successful Vault KV-v2 response at secret-{env}/mosaic-stack/database/importer (data.metadata.version), renders them as one immutable generation into separate consumer copies, and never infers a provider version from DSN bytes. The trusted runner verifies TLS/identity/manifest, reads its fixed importer URL/version copies only for binding through safe no-follow fd checks, and signs a credential-free JCS/Ed25519 attestation using its runner-only fixed root-owned private-key file; no signing key reaches importer/runtime. The artifact binds secret version and SHA-256 of exact high-entropy credential-file bytes, canonical TLS host/port/database, CA/SPKI, PostgreSQL system identifier/database OID, importer role, manifest/schema fingerprints, producer invocation/build/image digest, issued/expires/nonce, and correlation. Before target connection the importer validates URL/version/attestation/public-key files, signature/key/expiry/replay/authenticated provider version/digest/generation/bindings and the importer-only CA at exact DATABASE_TLS_CA_CERT_PATH; after verified TLS and before DML it validates server/database/role/CA/schema identity, with same-fd/in-memory-byte TOCTOU protection, rotation/revocation, a privileged producer-only-to-importer-only artifact handoff controller that verifies/copies/fsyncs/atomically renames/seals before importer start, consumer isolation/no logging-oracle, and sanitized errors. Raw --target-url, DATABASE_URL fallback, runtime-owner use, missing/unsafe/substituted files, stale/replayed/tampered/wrong-key attestation, wrong binding, and DDL attempt fail before target connection/DDL; post-connect mismatch closes with zero DML/DDL. A reviewed finite classifier inventories executable current source/scripts/package bins, operator docs, deploy manifests, and exact normative contracts by path; active secure records pin both options/files, producer/key/bindings/tests, while normative contracts cannot mask instructions. Unknown active commands, duplicate-owner, ownerless, missing-path, and historical/status-only masking hits fail. db:push is forbidden outside an explicitly disposable local developer database and cannot accept a production-like URL.
K101-REQ-02: Gateway runtime/replicas SHALL not execute migrations or DDL. The runner SHALL hold one max:1 session and fixed two-int advisory namespace 1297044289 (MOSA), 1262636593 (KBN1) across preflight, reconciliation, migration, verification, and release. It SHALL compare the versioned canonical manifest v1 tuple (journal logical index/tag plus exact SQL-byte SHA-256) to the complete observed ledger mapping; count/set-only, timestamps, and physical insertion order are non-normative and insufficient.
K101-REQ-03: PostgreSQL SHALL separate non-login platform database owner, non-login schema owner, dedicated NOLOGIN SUPERUSER mosaic_extension_owner, login migrator, dedicated login non-DDL data importer, non-login runtime capability, and login runtime roles. For PostgreSQL 17 + pgvector 0.8.2, vector is untrusted (trusted is absent and relocatable=true): only an externally controlled audited platform-bootstrap superuser session may SET ROLE mosaic_extension_owner for CREATE/UPDATE/SET SCHEMA, then RESET ROLE; the role has rolcanlogin=false, rolsuper=true, zero members, no runtime credential/Vault secret, and is never provided to app containers. It owns mosaic_extensions, fresh vector, and owner-bearing extension members, while mosaic_schema_owner receives only USAGE for type resolution and never ownership/CREATE/ALTER/DROP/member-change/default-privilege authority there. Superuser cannot be constrained by GRANT/REVOKE; this is identity/non-login/no-membership/external-control/audit isolation, not a false least-privilege claim. Extension operations require control-plane change, independent review, backup/rollback, maintenance window, and audit evidence. Managed targets that cannot establish this exact role are ineligible until an independently approved versioned provider-owned extension-owner profile exists; app/migrator ownership is never silently retained. Existing approved-owner extension relocation validates exact pg_namespace.nspowner, pg_extension.extowner, member ownership/schema/version, while legacy runtime-owned extension fails closed to a controlled shadow-database migration—never unsupported ownership alteration, catalog mutation, ownership adoption, or DROP CASCADE. Runtime, migrator, schema owner, importer, and all service roles must fail SET ROLE, catalog/direct ALTER/UPDATE/DROP/membership-change denial, role ownership, superuser/role-creation/schema-creation/TEMPORARY, unsafe membership, untrusted search path, missing grants, unauthenticated TLS, and immutable privilege drift checks. Application schema is fixed mosaic with exact pg_catalog,mosaic session path; historical public migrations remain byte-immutable legacy bootstrap only, every future Drizzle application declaration targets mosaic, and vector is explicitly qualified from non-writable mosaic_extensions. No config-derived SQL identifier is permitted.
K101-REQ-04: mosaicstack/stack KBN-101-00 SHALL exclusively own infra/pg-bootstrap/roles.sql, infra/pg-bootstrap/extensions.sql, infra/pg-bootstrap/README.md, and bootstrap tests; KBN-101-05 SHALL exclusively own tools/db/render-postgres-secrets.ts, its tests, and current Compose/Portainer/two-gateway deployment declarations, consuming the versioned bootstrap interface without overlap. Environment IaC/Vault is named input and Mosaic deployment control plane/Jason is activation authority. Distinct runtime/migrator/importer URL, importer authenticated provider-version, DB-client CA, Gateway leaf, and PostgreSQL server key/certificate materials are provisioned before a production-like database starts. Importer and migrator have separate immutable URL/version copies at fixed 10002:10002/10003:10003 identities; runtime/unrelated containers receive neither importer material, attestation private key, or importer artifact. Runtime, migrator, and importer require their mounted CA plus sslmode=verify-full. Exact UID/GID/mode/rendering, service-DNS SANs, Vault/compose/Swarm consumer isolation, two-gateway pair ordering, server activation, pre-enforcement legacy-client drain and hostssl zero-plaintext-session proof, fresh/existing transition, CA-overlap rotation, TLS-only rollback, and standalone/federated/Swarm/two-gateway positive/negative TLS evidence are required. No application-generated production certificate or plaintext bootstrap exception is permitted.
K101-REQ-05: KBN immutable relations SHALL permit the real runtime role INSERT/SELECT only and deny UPDATE/DELETE; parent retention remains RESTRICT/no-cascade. Role/password/Vault creation is external platform control, never application migration/source.
K101-REQ-06: N-1 single-URL compatibility, rollout/rollback, Vault ownership/rotation/redaction, CI, installer, compose/Portainer, observability, and deployment handoffs SHALL be separately bounded one-card/one-PR work. Prepared slices remain inactive while current owner-runtime deployments stay N-1; Mosaic control plane/Jason alone authorizes one final atomic activation or rollback, with no force-on-red/bypass. KBN-101 planning itself SHALL not mutate production.
K101-REQ-07: KBN-100 SHALL begin only after the KBN-101 foundation role/schema-boundary certificate; it SHALL rebase on that main head, restore generated Drizzle declaration/snapshot/journal consistency, and bound procedural immutable-table grant/trigger/backfill additions to its schema slice. KBN-101 real deployed-role immutable-operation certification SHALL complete after KBN-100 creates those relations and before KBN-105.

Acceptance criteria

AC-K101-01: DTO/command-matrix tests prove required modes, PGlite exception, mosaic-db-migrator --help|--run|--verify/stable exits/argv refusal, public-import negative, every finite classified DDL/static-bypass inventory path and both harness pairs reject DATABASE_URL-only before connection/DDL, no migration-to-runtime fallback, and db:push refusal outside an allowlisted disposable DB. Before inventory, ownership, or status masking, the semantic fixture fails README's exact former commented code-fence generic-wrapper form and the user guide's exact former executable generic-wrapper form; source-consistency proves current packages/storage/src/cli.ts directly execSyncs pnpm --filter @mosaicstack/db db:migrate and no mosaic-db-migrator bin exists, so runner-delegation documentation fails. The active docs/guides/migrate-tier.md route is inventoried to KBN-101-07 and proves runner-produced --target-url-file /run/secrets/mosaic-migrate-target-url, fixed paired provider-version file, and --target-attestation-file /run/mosaic-attestations/migrate-target.v1.json; runner-only signing/private-key isolation; Vault KV-v2 same-response version provenance, separate immutable generation mounts, importer CA, JCS/Ed25519 signature/key rotation/revocation, atomic artifact, expiry/replay, safe-fd secret-version/digest, canonical TLS/CA/server/database/role/manifest/schema bindings, dedicated non-DDL importer, consumer isolation/no log-oracle, and exact no-connection versus zero-DML rejection for missing/wrong/stale/replayed/tampered/wrong-key/substituted/generation-mismatched inputs. The full current non-normative docs inventory—including user guide, federation historical task/MILESTONES status, and non-operative SETUP—has an exact safe disposition. Scanner semantic checks reject automatic first-boot/startup extension/schema/migration wording, Compose-up-before-runner, init-script authority, production .env/monorepo auto-load/EnvironmentFile=/credential-export-or-argv/restart-as-secret-activation routes, and every unqualified operator-document mosaic-db-migrator --run|--verify hit regardless of named/normative/status classification. The exact former README/dev/deployment Compose-first sequences, former SETUP wording, exact former MILESTONES wording pgvector extension installed + verified on startup, former architecture-plan/PERFORMANCE/backlog runner routes, and any unqualified runner fixture fail before inventory masking. Only one Held future procedure Markdown section—bounded through the next equal-or-higher heading—may contain the explicit non-operative/no-current-command-authority form that names KBN-101-00/-03/-05 and preserves external bootstrap → TLS/roles → mosaic-db-migrator --run → mosaic-db-migrator --verify → Gateway/Compose readiness; every runner hit outside that section fails. The README assertion for the checked-in direct CI pnpm --filter @mosaicstack/db run db:migrate with DATABASE_URL passes only as active legacy N-1, uncertified, non-authorizing-as-an-operator-route status against an isolated disposable CI database pending KBN-101-06 removal—not as an ordinary operator or approved DDL-authority route. Only local PGlite data-layer work or non-PostgreSQL Compose is current (Gateway/Web local startup is held pending daemon/inherited/project-DSN rejection).
AC-K101-02: Fixed namespace lock contention/crash/readiness/non-interference and exact manifest-v1 reconciliation tests prove no replica race/runtime auto-migration and fail closed on every missing/unknown/duplicate/ambiguous/corrupt/stale ledger state.
AC-K101-03: Actual PostgreSQL 17 + pgvector 0.8.2 control-file, catalog, Drizzle-generation, vector-query/operator, fresh/approved-owner/legacy-shadow/partial/resume/rollback/N-1, and real deployed-role tests prove trusted absent/untrusted plus relocatability, external-superuser SET ROLE create/update/RESET ROLE audit, exact rolcanlogin=false/rolsuper=true/zero-membership/no-runtime-secret state, platform/schema/extension-owner/migrator/importer/runtime separation, pg_extension.extowner plus owner-bearing extension-member/schema/version assertions, and runtime/migrator/schema-owner/importer/all-service-role SET ROLE/ALTER/DROP/member-update denial. They also prove pg_catalog,mosaic per-session pool safety, mosaic_extensions qualification, identifier injection denial, ownership/membership/ledger-read/TEMP/default grants, and unsafe privilege denial.
AC-K101-04: Disposable standalone, federated/Swarm, and two-gateway verified-TLS positives plus for both pairs missing CA/wrong CA/wrong SAN/sslmode downgrade, server/Gateway key mode, UID/GID, secret-consumer isolation, and legacy-drain/hostssl negatives prove server bootstrap, ordering, and readiness; PGlite is expressly excluded from this PostgreSQL evidence.
AC-K101-05: Real runtime-role evidence proves INSERT/SELECT succeeds and UPDATE/DELETE fails for every frozen immutable KBN relation.
AC-K101-06: N-1/atomic activation/rollback, Vault/CA-overlap rotation/redaction, health/operator behavior, CI/deployment handoff, independent exact-head security review, and terminal-green CI evidence the foundation before KBN-100; after KBN-100, the real deployed-role immutable-operation certificate and Ultron approval release KBN-105.

Normative implementation contract: docs/native-kanban-sot/KBN-101-DB-ROLE-SPLIT.md. ASSUMPTION: existing standalone and federated are all PostgreSQL production-like modes; any new PostgreSQL tier inherits these requirements until an explicit versioned amendment.

Tess Interaction Agent Workstream (TESS)

Problem and Objective

Jason needs one durable, operator-facing Mosaic agent outside Hermes that is reachable through a dedicated Discord channel and CLI, can attach to and operate the Mosaic fleet and transitional Hermes agents, and preserves context across restarts and compaction. Mos remains the coding/general fleet orchestrator; Tess is the complementary human interaction, visibility, control, and migration agent.

The objective is to ship Tess (from tessera, a piece of a mosaic) as a Pi-native, GPT-5.6 Sol agent with high reasoning. Tess must use Mosaic-owned contracts and plugins so Hermes can be replaced incrementally rather than becoming a permanent architectural dependency.

Scope

In Scope

TESS-ARP-001: A runtime-neutral AgentRuntimeProvider contract supporting listSessions, streamSession, sendMessage, terminate, getSessionTree, attach, health, capability discovery, and normalized events/errors.
TESS-PI-001: A long-running Pi-native Tess agent profile/service pinned to GPT-5.6 Sol with high reasoning, explicit tool policy, lifecycle hooks, durable checkpoints, and restart recovery.
TESS-DSC-001: Dedicated Discord channel binding to Tess through the Mosaic gateway, with allowlists/RBAC, thread/reply policy, streaming, attachments, approvals, and correlation IDs.
TESS-CLI-001: mosaic tess CLI commands for chat, status, session listing, attach/detach, send/steer/stop, provider health, and recovery.
TESS-FLT-001: Fleet plugin capabilities for roster/status/heartbeat inspection, message delivery, session hierarchy, safe attach, and controlled restart/recovery.
TESS-MOS-001: Explicit Mos coordination boundary and tools: hand off orchestration requests, observe mission/task state, receive results, and never silently compete for orchestration authority.
TESS-HRM-001: Transitional Hermes adapter for profiles/agents, sessions, streaming/messages, Kanban, skills, memory, tools, cron, and health, using capability negotiation and fail-closed unsupported operations.
TESS-MEM-001: Unified memory/retrieval plugin with scoped search/recent/capture/stats, startup context injection, provenance, redaction, namespace isolation, and flat-file/project truth precedence.
TESS-STA-001: Durable agent state, inbox, handoff, compaction-recovery, and resume reconstruction.
TESS-PLG-001: Plugin/tool catalog covering runtime bootstrap, repository/PR workflow, fleet diagnostics, incident-safe read operations, Discord interaction, and extensible MCP/skill discovery.
TESS-TRN-001: Replaceable transport providers: tmux/fleet now, Matrix/native Mosaic transport later, with no Discord/CLI business logic coupled to transport details.
TESS-SEC-001: RBAC, per-operation authorization, explicit approval for destructive/privileged/customer-visible actions, audit events, secret/PII redaction, tenant isolation, and bounded command execution.
TESS-SEC-002: Command execution SHALL enforce declared scope/role server-side; admin/system and destructive operations SHALL require policy-bound durable approval.
TESS-SEC-003: Every session list/read/attach/send/terminate operation SHALL enforce server-derived owner and tenant scope; guessed or client-supplied IDs SHALL grant no authority.
TESS-SEC-004: MCP tools SHALL derive actor/tenant from authenticated context and SHALL NOT accept caller-controlled identity fields.
TESS-SEC-005: Discord plugin ingress SHALL authenticate service identity, enforce guild/channel/user allowlists, propagate correlation/message IDs, and reject replay.
TESS-SEC-006: Secret/PII classification and redaction SHALL occur before persistence and before channel egress, including tool metadata and authentication flows.
TESS-SEC-007: Approvals SHALL be one-time, expiring, actor/tenant-bound, and cryptographically bound to the exact structured action digest.
TESS-SEC-008: Ingress, provider sends, tool side effects, and responses SHALL use durable inbox/outbox/checkpoints and idempotency records for restart-safe replay.
TESS-SEC-009: Garbage collection and retention SHALL be session/tenant scoped unless executed as a separately authorized and audited system-wide job.
TESS-OBS-001: Structured logs, traces, health/readiness, provider latency/errors, session lifecycle, tool audit, and actionable recovery diagnostics.
TESS-MIG-001: Capability inventory and staged Hermes-to-Mosaic migration matrix with coexistence, cutover, rollback, and deprecation gates.

Out of Scope

Replacing Mos as coding/general fleet orchestrator.
Making Hermes the Mosaic core or coupling Mosaic domain logic to Hermes schemas.
Migrating every historical chat verbatim; only policy-compliant indexed summaries and user-selected sessions are migrated.
Unrestricted shell execution from Discord.
Full web UI parity in the first Tess operational milestone; gateway contracts must remain web-consumable.
Replacing tmux before Matrix/native transport reaches operational parity.

Stakeholder and User Requirements

Jason must be able to converse with the same Tess session from Discord and CLI.
Jason must be able to see what is running, stale, blocked, or unhealthy without attaching manually to every session.
Jason must be able to attach to Tess and authorized fleet sessions through supported CLI controls.
Tess must collaborate with Mos and the fleet while preserving a single clear orchestration authority.
The system must migrate useful Hermes/OpenClaw capabilities intentionally, with evidence, instead of copying implementations wholesale.

Non-Functional Requirements

Security: default-deny provider/tool capabilities, least privilege, no secrets in logs/prompts/commits, Discord user/channel authorization, and auditable approvals.
Reliability: durable inbox/checkpoints; idempotent message handling; reconnect with bounded backoff; no message loss or duplicate execution across gateway restart.
Performance: first acknowledgement within 2 seconds when connected; streamed agent output begins within 5 seconds excluding model/provider delay; status reads return within 2 seconds under nominal local conditions.
Observability: every ingress message and resulting provider/tool operation carries a correlation ID across Discord, gateway, Tess, provider, and audit events.
Maintainability: channel, runtime, transport, memory, and external-agent integrations remain adapter-based with contract tests.
Privacy: only scoped context enters external runtimes; persisted messages/memories follow retention and redaction policy.
Portability: Tess runs through Pi/Mosaic contracts and does not require Hermes to start or serve native Mosaic operations.

Acceptance Criteria

AC-TESS-01: A dedicated Discord channel and mosaic tess chat connect to one durable Tess session and stream responses bidirectionally.
AC-TESS-02: mosaic tess status|sessions|tree|attach|send|stop operate against authorized provider capabilities with stable typed outputs and actionable errors.
AC-TESS-03: Tess runs GPT-5.6 Sol at high reasoning and its effective runtime/model/tool policy is visible through status without exposing credentials.
AC-TESS-04: Tess can inspect and message the Mosaic fleet, hand orchestration work to Mos, and demonstrate that Tess does not independently claim Mos-owned orchestration work.
AC-TESS-05: Hermes adapter demonstrates session listing, streaming/message delivery, hierarchy mapping, and at least one approved capability in each of Kanban, skills, memory, tools, and cron—or reports unsupported capabilities fail-closed.
AC-TESS-06: Restart/compaction test preserves session identity, pending inbox, last durable checkpoint, and a resumable handoff without duplicate side effects.
AC-TESS-07: Unauthorized Discord users/channels, cross-tenant access, unsafe tool calls, forged approvals, and sensitive-output cases are denied and audited.
AC-TESS-08: tmux/fleet and Matrix/native transport implementations pass the same provider contract suite; Matrix may remain non-default until readiness gates pass.
AC-TESS-09: Baseline quality gates, unit/integration/contract tests, Discord+CLI E2E, restart/recovery tests, independent code review, and security review are green.
AC-TESS-10: Migration matrix documents every audited Hermes/OpenClaw capability as native, adapted, deferred, or rejected, with cutover and rollback evidence.
AC-TESS-11: User, admin, developer, API/OpenAPI, operations/recovery, and plugin-authoring documentation is current and linked from the sitemap.

Constraints, Dependencies, Risks, and Assumptions

Dependency: Mosaic gateway remains the single API surface; Pi is the native runtime; Valkey/PostgreSQL provide canonical durable state where required.
Dependency: Discord bot credentials and dedicated channel ID are deployment secrets provisioned outside source control.
Risk: Tess could drift into a second orchestrator. Mitigation: explicit role policy, Mos handoff contract, authority checks, and E2E boundary tests.
Risk: broad Hermes compatibility can freeze legacy semantics into Mosaic. Mitigation: Mosaic-owned normalized contracts and capability negotiation.
Risk: Discord creates a privileged remote-control surface. Mitigation: pairing/allowlists, RBAC, approvals, rate limits, audit, and safe tool classes.
Risk: transcript ingestion can violate privacy or overload memory. Mitigation: scoped opt-in import, redacted summaries, provenance, retention, and deduplication.
Risk: current root filesystem has limited headroom. Mitigation: isolated worktrees, no duplicated dependency installation unless required, and cleanup only after active-lane verification.
ASSUMPTION: The public name is Tess, because the user requested a name and the tessera/Mosaic relationship is distinctive; config must permit later display-name changes without renaming APIs or storage keys.
ASSUMPTION: The dedicated Discord channel ID and final guild policy will be supplied/provisioned during deployment, so implementation uses explicit configuration and fail-fast startup validation.
ASSUMPTION: tmux/fleet is the production transport for the first operational milestone; Matrix/native transport is implemented behind the same contract and promoted only after parity/reliability verification.
ASSUMPTION: Project/task truth remains in canonical Mosaic/project stores; semantic memory systems are retrieval/mirror layers, not hidden authorities.

Testing and Delivery Intent

Delivery uses five gated milestones: runtime contracts/security; Pi service/state; Discord/CLI; fleet/Hermes/plugin suite; migration/Matrix/recovery/qualification. Every source-code task requires tests, independent review, a PR to main, terminal-green CI, and issue/task closure. Production activation additionally requires a clean-host Pi launch, dedicated Discord channel smoke test, CLI attach test, restart/recovery drill, and rollback procedure.

Official Channel Plugin Workstream (#756)

Problem and Objective

The Discord plugin currently couples Discord event handling, gateway bridging, and reply routing in one implementation and activates only on mentions. Mosaic needs an official channel adapter that behaves the same no matter whether the bound logical agent currently runs through Claude, Codex, Pi, OpenCode, or a future harness. The Discord connection and conversation address must remain stable while the gateway changes the runtime provider behind that logical session.

The objective is to make Discord the first implementation of a transport-neutral official channel contract, with explicit authorization and deterministic channel/thread routing that future Matrix, Slack, and other adapters can share.

Scope

In Scope

CHN-001: Transport-neutral channel adapter, route, message, attachment, authorization-principal, response-target, and health contracts in @mosaicstack/types, including trusted per-binding logical-agent configuration selection.
CHN-002: Stable channel conversation addresses based on logical agent plus channel/thread identity; harness, model, and runtime-provider IDs are forbidden from channel session keys.
DSC-001: An authorized untagged message in a configured agent-bound channel routes to the agent and receives its response in that channel.
DSC-002: A bot mention in a configured parent channel creates a Discord thread, or reuses the thread already attached to that same native message; the mentioned turn and subsequent thread turns route and respond in that thread.
DSC-003: A message already inside an authorized thread inherits authorization from its configured parent and never attempts a nested thread.
DSC-004: Guild, parent channel, user, pairing, and role authorization remains default-deny before thread creation or gateway dispatch.
DSC-005: Discord service authentication, HMAC envelope integrity, replay protection, attachments, approvals, response chunking, and correlation behavior remain intact.
DSC-006: The Discord adapter exposes lifecycle and health behavior through the shared channel contract without importing a harness SDK.

Out of Scope

The logical-agent lease, fencing epoch, execution grant, checkpoint, or cross-harness takeover implementation tracked by #754/#755.
Dynamic Discord authorization administration in the web UI.
Multi-guild tenant isolation, DMs, slash commands, voice, reactions, or production bot deployment.
Implementing Matrix or Slack adapters in this slice.

Non-Functional Requirements

Security: no thread or dispatch side effect occurs until guild, parent channel, user, pairing, role, and bounded per-user/channel rate checks pass; attachment metadata is shape- and size-bounded; credentials never enter source, messages, session keys, or logs.
Portability: channel contracts and stable conversation IDs contain no Claude, Codex, Pi, OpenCode, model, process, or provider-specific field; each configuration-owned binding selects its trusted logical agent without changing the channel identity.
Reliability: repeated messages for one channel/thread resolve the same conversation handle; reconnecting the adapter does not require a harness-specific rebinding.
Maintainability: Discord-specific API translation stays in the Discord package; gateway and future adapters depend on transport-neutral contracts.
Observability: thread creation or routing failure is reported without message content or credential material.

Acceptance Criteria

AC-CHN-01: Contract and behavior tests prove the plugin route contains only logical agent plus channel/thread identity and produces the same stable conversation handle regardless of underlying harness selection.
AC-CHN-02: A mentioned authorized parent-channel message creates a thread (or reuses its already-attached thread), dispatches to the thread conversation, and targets the response to that thread.
AC-CHN-03: An untagged authorized parent-channel message dispatches to the parent conversation and targets the response to the parent channel.
AC-CHN-04: Untagged follow-ups inside an authorized thread dispatch and respond in that same thread without creating a nested thread.
AC-CHN-05: Unauthorized guilds, channels, users, unpaired users, insufficient roles, and rate-limited senders produce no thread and no gateway dispatch.
AC-CHN-06: Shared channel contracts are exported from @mosaicstack/types, Discord implements the lifecycle/health seam, and no harness SDK is imported by the plugin.
AC-CHN-07: Focused routing/auth tests, package tests, typecheck, lint, formatting, coverage, independent code/security review, and terminal-green CI pass.

Constraints, Risks, and Assumptions

Dependency: Mosaic gateway remains the policy, durable-session, audit, and runtime-provider boundary.
Constraint: This work must not modify orchestrator-to-Pi migration or #754/#755 lease/fencing files.
Risk: accepting untagged messages could create noisy or unintended agent input. Mitigation: only explicitly configured channels and paired, role-authorized users are accepted, with bounded per-user/channel message and thread rates.
Risk: Discord thread creation can fail because of channel permissions, archived state, or API rate limits. Mitigation: fail without dispatching a turn whose response destination cannot be honored, and emit sanitized diagnostics.
ASSUMPTION: Configured channels are dedicated agent interaction surfaces, so authorized untagged human messages are intentional agent input.
ASSUMPTION: Mention in a parent channel selects a public thread; messages already in a thread remain there because Discord has no nested threads.
ASSUMPTION: One Discord bot may serve multiple configuration-owned logical-agent bindings.
ASSUMPTION: Static allowlists and paired-user roles are the authorization administration surface for this slice.

Testing and Delivery Intent

Use TDD for remote-ingress routing and permission boundaries. Required evidence includes parent-channel mention, untagged parent message, existing-thread follow-up, existing-thread mention, thread reuse, unauthorized side-effect denial, stable harness-neutral conversation identity, adapter health, and regression coverage for signed envelopes and approvals. Deliver through issue #756, a reviewed squash PR to main, terminal-green CI, and issue closure.

Mos Runtime Portability Workstream (MOS-PORT)

Problem and Objective

Mos is currently identified partly by a harness-native session and communication process. Replacement/rebinding exists, but no gateway-enforced logical identity or fencing prevents a stale harness from continuing to reply or execute effects after takeover.

The objective is to make Mos a server-derived logical Mosaic identity whose authority can move safely among runtime connectors. The gateway owns identity, lease, policy, and audit; harnesses remain replaceable adapters.

M1 Requirements

MOS-PORT-ID-001: Define a normalized logical-agent identity independent of Claude Code, Pi, Codex, tmux, Matrix, and provider-native session IDs.
MOS-PORT-LEASE-001: Persist one exclusive connector lease per tenant/logical-agent/binding with CAS acquisition, monotonic fencing epoch, TTL, heartbeat, explicit release, and takeover.
MOS-PORT-FENCE-001: Bind every connector dispatch/execution grant to the current server-derived tenant, logical identity, binding, connector, scopes, expiry, and lease epoch.
MOS-PORT-FENCE-002: Reject and audit stale, expired, forged, cross-tenant, cross-binding, and unauthorized grants before connector, channel, provider, or tool side effects.
MOS-PORT-OBS-001: Emit credential-safe correlation/audit events for lease acquire, renew, takeover, reject, release, and expiry.
MOS-PORT-ARCH-001: Runtime/provider adapters consume normalized lease context without adding harness-native schemas to Mosaic core.

M1 Acceptance Criteria

AC-MOS-PORT-01: Two contenders for one binding cannot simultaneously hold current authority under concurrency.
AC-MOS-PORT-02: Successful takeover increments the fencing epoch and every operation from the old epoch fails closed before side effects.
AC-MOS-PORT-03: Gateway/database restart preserves lease and epoch state; expired leases can be recovered only through the authorized takeover path.
AC-MOS-PORT-04: Cross-tenant, cross-agent, cross-binding, forged, and expired lease/grant cases are denied and audited.
AC-MOS-PORT-05: Unit, migration, repository close/reopen, concurrency, abuse, gateway integration, independent security review, CI, and documentation gates pass.

Deferred to Later #754 Milestones

Canonical checkpoint/handoff payloads, exactly-once connector receipts, concrete Claude/Pi/Codex adapters, channel cutover, and full cross-harness failover/rollback E2E are explicitly out of M1 scope.

Workspace placement guard hardening (#1174)

Problem and objective

The Bash pre-tool guard must prevent Git checkouts and repository state from being placed under $HOME without refusing ordinary Git commands merely because a source, option value, branch name, or metadata mentions $HOME. A guard that over-blocks routine work is unsafe because operators will route around it.

Scope and requirements

WPG-REQ-01: git clone and git worktree add placement SHALL be judged from their placement operands, not from every HOME-shaped word in the command.
WPG-REQ-02: Clone sources, references, templates, environment assignments, and non-placement worktree metadata MAY resolve under HOME when all placement operands resolve elsewhere.
WPG-REQ-03: Both attached and separate-value --separate-git-dir forms SHALL remain placement operands and SHALL be refused when they resolve under HOME.
WPG-REQ-04: Option classification SHALL account for Git's rule-generated boolean negations without relying on an enumerable allowlist of flag spellings.
WPG-REQ-05: Quote removal, escapes, shell command boundaries, redirections, and end-of-options handling SHALL preserve existing fail-closed checkout coverage.
WPG-REQ-06: Absolute placement aliases SHALL resolve shell-known HOME spellings, dot segments, repeated separators, and existing symlink parents before the HOME boundary comparison.
Relative targets whose effective path depends on the shell cwd are out of scope and tracked by #1197.

Acceptance and verification

Git's own option parser accepts each tested flag, including generated --no-* forms, while the guard allows a HOME-valued source with an explicit safe destination.
Equivalent clone and worktree fixtures cover rule-generated negations and remain discriminating against the prior head where the defect existed.
Real HOME destinations and both --separate-git-dir forms remain blocked, including placements after shell command boundaries.
The full hermetic guard suite, syntax/static checks, adversarial probes, independent review, and terminal-green CI pass before merge.
Any option-classification residual is documented with its deliberate failure direction.

Constraints, risks, and assumptions

Security and usability are co-equal: neither a placement bypass nor routine over-block is an acceptable repair.
ASSUMPTION: The value-taking option surface exposed by the installed Git version is closed and measurable through Git's own parser/help output; rationale: boolean flags are rule-generated, while separate-value options have explicit grammar and must be classified as such.
Risk: a future Git release may add a new value-taking placement option. Mitigation: document the chosen residual direction and pin every currently supported placement option in behavior tests.
Risk: a symlink can be replaced after pre-execution canonicalization. Mitigation: resolve every existing parent physically and document the remaining inherent TOCTOU window; the worktree helper remains the authoritative path-derivation mechanism, with atomic closure tracked by #1199.

Release Integrity Workstream (RI, #1275)

Problem and objective

At next 476db12b (review of 2026-08-17), publication from next is not bound to the full verification pipeline for the same commit: the publish pipeline's publish steps depend on build only, while ordinary push CI excludes next. Public Forge/MACP paths contain false-success placeholders: a stub executor that reports completed with exit zero, planning/remediation gates that execute literal true, a review gate that echoes an approving verdict, and a gate runner that treats empty commands and unimplemented CI-provider gates as passing. Shipping UI surfaces can render a failed fetch as an empty, healthy collection.

Objective: for alpha 0.0.50, the release cannot publish, report, or display work state that the repository has not actually verified. Decisions SDLC-D-033 through SDLC-D-038 (Jason, 2026-08-17) scope this floor; full decision text and required-behavior lists live in jarvis-brain docs/plans/2026-08-16_mosaic-stack-sdlc-protocol.md and data/decisions/mosaic-stack-sdlc-protocol.json. This section restates only the normative requirements.

Normative requirements

RI-N1 Exact-commit publication verification (SDLC-D-034). One canonical terminal verification command performs self-contained re-verification in the publish pipeline against the job's checked-out commit before any external publication effect. The command contains or invokes the complete mandatory verification set (semantic parity with the PR merge gate, including sanitization, upgrade-guard, typecheck, lint, format check, tests, and build); CI and publication do not maintain separate semantic checklists. Every publish step depends on the verification step in the executable pipeline DAG. Provider commit identity and git rev-parse HEAD must identify the same commit. Missing, skipped, cancelled, stale, or inconclusive checks fail closed. Documentation-only runs may skip publication but cannot bypass verification when a publication effect will occur. A negative control must prove that a broken check blocks every publish step.
RI-N2 Fail-closed Forge/MACP with explicit simulation (SDLC-D-035). Simulation requires explicit caller intent (e.g. --simulate) and produces a distinct typed simulated state that can never satisfy dependencies, acceptance criteria, gates, merge, or release. Normal execution exits nonzero with a typed capability failure when a required executor, reviewer, command, or CI provider is absent — no stub completion, no literal-true gates, no synthetic approvals, no empty-command passes. A manual gate with no automation enters a waiting state; it does not pass. Positive tests prove explicit simulation still works; negative controls prove simulation and every missing-provider case cannot advance lifecycle state.
RI-N3 One transitional PRD authority (SDLC-D-036). @mosaicstack/prdy structured storage under docs/prdy/, driven by mosaic mission --plan, is the authoritative PRD representation for the alpha. mosaic prdy either routes through the same application service or operates only as an explicit, named Markdown import/export adapter; docs/PRD.md is not a peer authority. mission --plan must persist the mission↔PRD linkage (mission id/version, PRD id/version, selected requirements). Markdown output is a generated view carrying source identity; editing it cannot mutate authority silently. Import is explicit, validated, and conflict-aware (proposed successor, never overwrite). Structural validity is separate from approval.
RI-N4 One quality-rails evaluator (SDLC-D-037). The TypeScript quality-rails package is the sole authoritative evaluator. A complete probe inventory maps every current TypeScript and shell check to one canonical check with disposition (preserve/strengthen/retire, each named). Effective shell enforcement probes are absorbed before their independent paths retire; expected-file presence alone is not parity. The evaluator returns typed results (passed/failed/blocked/error/not-applicable) with check version, subject, and reason; missing implementation, missing input, unknown check, process error, timeout, or malformed output can never become passed or an unqualified skip. Check definitions and policy are versioned and digested. Shell commands become thin adapters with no separate verdict logic. The canonical terminal verification command (RI-N1) invokes this evaluator rather than duplicating its logic. Contract, parity, and negative-control tests are required, plus independent review of probe equivalence.
RI-N5 Consequence-aware stale UI (SDLC-D-038). Mission Control distinguishes typed freshness states (current, stale, partial, unknown, unavailable) rather than inferring from empty arrays or null. A failed fetch never renders as an empty healthy collection. Last-known data may display for situational awareness only with source identity, version, and age visibly labeled; any derived completion/assurance/release verdict whose inputs are stale becomes unknown; all state-changing actions are disabled until fresh state loads and is revalidated. With no verified snapshot, surfaces show an explicit unavailable state. Cache corruption, cross-workspace data, schema mismatch, and version regression invalidate the snapshot. Tests cover the failure matrix (network, auth, malformed, partial, corruption, stale age, schema mismatch, recovery, stale-action rejection) with negative controls proving no case yields a current green verdict or enabled mutation.

Acceptance criteria

AC-RI-1: A push to next that fails any mandatory verification step publishes nothing (no npm package, no image), demonstrated by a checked-in negative control and by pipeline evidence on a real next publish run where the verification step is green and every publish step depends on it.
AC-RI-2: With no executor/reviewer/CI provider wired, Forge and MACP normal runs exit nonzero with typed capability failures; with --simulate, runs complete but every result is typed simulated and cannot satisfy any gate, dependency, or completion state — proven by unit tests including negative controls.
AC-RI-3: A PRD created or revised through either mosaic mission --plan or mosaic prdy resolves to one authority under docs/prdy/ with stable identities and versions; the mission↔PRD linkage survives restart; a Markdown export is labeled as generated and cannot silently become a second writer; divergent legacy content blocks baseline claims until explicitly resolved — proven by contract tests.
AC-RI-4: quality-rails check through any entry point (TS CLI, framework shell adapter) returns the same typed verdict for the same subject; the probe inventory names every legacy check's disposition; a deliberately broken probe fails closed — proven by contract/parity/negative-control tests and independent review of probe equivalence.
AC-RI-5: No shipping surface renders a failed fetch as an empty healthy state; stale/partial/unavailable states are typed, labeled, and mutation-disabled — proven by the failure-matrix tests.
AC-RI-6: All cards merged to next via squash PR with terminal-green CI; release evidence for 0.0.50 records commit, verification run, and published artifacts.

Out of scope

The canonical dispatcher/control-plane vertical slice (work graph, execution attempts, fenced leases, typed check-in, independent verifier dispatch) is decided post-alpha (SDLC-D-033, option B). Multi-pipeline verification certificates (SDLC-D-034 option B) are post-alpha. Full AF-1..AF-4 objective matrices and Mission Control portfolio surfaces are post-alpha.

86 KiB Raw Blame History Unescape Escape

PRD: Mosaic Stack — North Star

Metadata

Part I — Product north star

1. What Mosaic Stack is (D1)

2. Who it is for (D1, D9)

3. Deployment modes (D3)

4. Structure and tenancy (D2, D9, D13)

5. Identity (D10)

6. Onboarding (D4)

7. Data custody (D6, D14)

8. Architecture gate — the webUI sits OVER official tooling (D8, D12)

9. v1 slice (D11)

10. Relationship to the fleet north star

11. Explicit non-goals

12. Decision registry

12.1 Drafting additions beyond D1–D14

Part II — Active workstream contracts (preserved unchanged)

Current addendum: #1194 — Installed framework-tool drift detection

Compaction Refresh Trust Lifecycle (M1, #827–#830)

Problem and objective

Requirements

Acceptance criteria

Pi Persistent Goal Loop (#1150)

Problem and objective

Scope

In scope

Out of scope

User and stakeholder requirements

Non-functional requirements

Acceptance criteria

Constraints, risks, and assumptions

Testing and delivery intent

Fleet Declarative Configuration Management Workstream (FCM, #758)

Problem and objective

Normative requirements

Acceptance criteria

M0 implementation gate

Fleet git identity launch propagation (#1043)

Problem and objective

Normative requirements

Acceptance criteria

Framework shell assertion portability (#1098)

Problem and objective

Normative requirements

Acceptance criteria

Exact Cross-Harness Fleet Communications Contract (#766)

Problem and objective

Normative requirements

Acceptance criteria

KBN-101 Database Runtime/Migration Role Split (#771)

Problem and objective

Normative requirements

Acceptance criteria

Tess Interaction Agent Workstream (TESS)

Problem and Objective

Scope

In Scope

Out of Scope

Stakeholder and User Requirements

Non-Functional Requirements

Acceptance Criteria

Constraints, Dependencies, Risks, and Assumptions

Testing and Delivery Intent

Official Channel Plugin Workstream (#756)

Problem and Objective

Scope

In Scope

Out of Scope

Non-Functional Requirements

Acceptance Criteria

Constraints, Risks, and Assumptions

Testing and Delivery Intent

Mos Runtime Portability Workstream (MOS-PORT)

Problem and Objective

M1 Requirements

M1 Acceptance Criteria

Deferred to Later #754 Milestones

Workspace placement guard hardening (#1174)

Problem and objective

86 KiB

Raw Blame History