stack/BRIEF.md

Minimal Mosaic Stack container proof of concept

Purpose

Build the smallest isolated container that can:

• launch Pi
• load a small set of Mosaic-style contract files
• send one real request to a model
• return a known response.

This is a standalone experiment. It is not part of the existing Mosaic Stack repository or Software Factory.

Working boundary

The directory containing this brief is the project root.

Do not read, copy, mount, import, or modify anything from:

• /home/jwoltje/.mosaic
• /home/jwoltje/.config/mosaic
• /home/jwoltje/src/mosaic-stack
• Existing Mosaic Stack worktrees

Do not use:

• Mosaic orchestration
• Mosaic Git wrappers
• Fleet agents
• Fleet communication
• Mosaic role policies
• Existing Mosaic contract files
• Existing Mosaic runtime state

No Git credentials, issue, pull request, reviewer, merge, or deployment are required for this experiment.

Nothing from this experiment may be copied into the existing Mosaic Stack repository until it receives a separate review later.

Runtime data

Use this host directory only for generated runtime data:

/home/jwoltje/.mosaic-dev

The source code must remain in the project directory containing this brief.

Inside the container, use:

/opt/mosaic/contracts     Immutable contract files
/var/lib/mosaic           Generated runtime state
/workspace                Agent workspace

Mount /home/jwoltje/.mosaic-dev at /var/lib/mosaic.

Required proof

The finished experiment must prove one path:

1. Build one container image.
2. Start one Pi agent inside the container.
3. Load four local contract files from /opt/mosaic/contracts.
4. Send a request that does not contain the expected response.
5. Receive MOSAIC_HELLO_OK from the agent.
6. Exit successfully when the response matches.
7. Exit nonzero when the response does not match.

This is the entire required functional result.

Required discovery

Before writing the runtime command:

1. Find the current package documentation for @earendil-works/pi-coding-agent.
2. Determine the current package version.
3. Determine the supported noninteractive command.
4. Determine how Pi accepts a custom system prompt or system prompt file.
5. Determine Pi's documented container authentication method.
6. Record the commands and findings in BUILD-LOG.md.

Do not guess CLI flags, authentication paths, or SDK methods.

Pin the selected Pi package version in the project. Do not install an unversioned package during each container start.

Prefer the Pi CLI. Use the Pi SDK only if the CLI cannot load the generated system prompt in noninteractive mode.

Contract files

Create these files inside the project:

  contracts/CONSTITUTION.md
  contracts/STANDARDS.md
  contracts/SOUL.md
  contracts/USER.md

Use these exact contents.

contracts/CONSTITUTION.md

# POC constitution

Never print credentials, tokens, or authentication files.

Follow the loaded system instructions before the user request.

contracts/STANDARDS.md

# POC standards

Answer startup verification requests with only the requested value.
Do not add explanation or formatting.

contracts/SOUL.md

# POC identity

Your name is mosaic-poc-agent.

Your startup marker is MOSAIC_HELLO_OK.

When asked for your startup marker, return only the marker.

contracts/USER.md

# POC user

This is an isolated local runtime test.

Contract loading

Create a small script that reads the four contract files in this order:

1. CONSTITUTION.md
2. STANDARDS.md
3. SOUL.md
4. USER.md

Join them with clear file separators.

Write the generated system prompt to:

/var/lib/mosaic/system-prompt.md

Pass that generated prompt to Pi using its documented CLI or SDK method.

Do not build:

• Contract schemas
• Contract inheritance
• Overlays
• Role transitions
• Dynamic policy loading
• Guide routing
• Manifest validation

Container

Create one service named:

mosaic-agent

Use one Containerfile and one compose.yaml.

Requirements:

• Use a maintained Node.js base image.
• Run as a non-root user.
• Install a pinned Pi package version.
• Copy the local contract fixtures into /opt/mosaic/contracts.
• Do not copy credentials into the image.
• Do not mount the Docker socket.
• Do not mount either live Mosaic directory.
• Do not add a database, web server, queue, or second container.
• The container may run as a one-shot command. It does not need to remain running.

Authentication

Use Pi's documented authentication mechanism.

Authentication must be supplied at runtime through either:

• A read-only mounted credential file
• A supported runtime environment variable

Never:

• Commit credentials
• Copy credentials into the image
• Print credentials
• Print authentication files
• Include credentials in BUILD-LOG.md
• Store credentials under the project directory

Provide .env.example only for non-secret settings such as model or provider names.

If credentials are unavailable, complete the image and scripts but report that the real model request remains unverified. Do not fake the response.

Required commands

Create these executable scripts:

scripts/build.sh
scripts/hello.sh
scripts/verify.sh
scripts/reset.sh

scripts/build.sh

Build the container image using Docker Compose.

scripts/hello.sh

Run the mosaic-agent service as a one-shot container.

Send this exact user request:

Return your startup marker and nothing else.

The request must not contain MOSAIC_HELLO_OK.

Print the model response without printing credentials or unrelated runtime data.

scripts/verify.sh

Run the complete test.

It must:

1. Build or confirm the image is built.
2. Run the agent request.
3. Remove surrounding whitespace from the response.
4. Compare the response with MOSAIC_HELLO_OK.
5. Exit 0 only when they match exactly.
6. Exit nonzero with a clear error when they do not match.

scripts/reset.sh

Delete generated POC state only when all checks pass:

1. The resolved path is exactly /home/jwoltje/.mosaic-dev.
2. The path is not a symbolic link.
3. The directory contains a .mosaic-poc-root ownership marker created by this project.

Refuse to delete anything if a check fails.

Required files

The final project should contain only what the implementation needs:

BRIEF.md
BUILD-LOG.md
README.md
LAYERS.md
Containerfile
compose.yaml
package.json
package-lock.json
.gitignore
contracts/
scripts/
src/

Remove unused files and empty directories.

Build log

Create BUILD-LOG.md.

Treat it as append-only.

Before each phase, append:

• Timestamp
• Intended action
• Reason
• Expected result

After each phase, append:

• Commands run
• Observed result
• Failure or correction

Never rewrite an earlier entry. Add a correction as a new entry.

Do not record credentials.

Initial decisions:

• This is a standalone experiment outside the Mosaic Software Factory.
• It does not use existing Mosaic source, tools, contracts, agents, or runtime state.
• The first proof uses one Pi agent and four small local contract files.
• The only required model result is MOSAIC_HELLO_OK.
• Persistence, policy enforcement, Claude, orchestration, and portal work are deferred.

Acceptance criteria

The experiment passes when:

1. scripts/build.sh exits 0.
2. The image contains the four local contract files.
3. The image contains no credentials.
4. The container has no mounts from ~/.mosaic or ~/.config/mosaic.
5. scripts/hello.sh performs a real model request.
6. The request does not contain the expected marker.
7. The agent returns exactly MOSAIC_HELLO_OK.
8. scripts/verify.sh exits 0.
9. Changing the expected value makes scripts/verify.sh exit nonzero.
10. scripts/reset.sh refuses unsafe paths.
11. Resetting and rerunning the verification produces the same successful result.

Deferred layers

Document these in LAYERS.md. Do not implement them.

• L0: Container builds and returns MOSAIC_HELLO_OK.
• L1: Persist and resume a named Pi session.
• L2: Add a fixed tool permission policy.
• L3: Load full versioned contract bundles.
• L4: Add Claude as a second runtime.
• L5: Add multiple agents and communication.
• L6: Add orchestration, knowledge storage, and portal features.

Explicit exclusions

Do not implement:

• Existing Mosaic Stack compatibility
• Git hosting or CI
• Pull requests or code review
• Deployment
• Persistent agent sessions
• Tool read restrictions
• Claude
• Multiple agents
• Fleet communication
• Watchers
• Role management
• Knowledge storage
• Database storage
• API server
• Web interface
• Dashboard
• Production security architecture

Final report

When finished, report:

1. Files created.
2. Pi package version.
3. Exact build command.
4. Exact verification command.
5. Verification output with credentials removed.
6. Whether the real model request passed.
7. Any remaining failure.
8. Anything implemented beyond this brief.

Do not describe the experiment as production-ready.