stack/docs/plans/2026-09-06_workspace-schema-and-audit.md

# Workspace schema and execution audit discussion

Status: proposed details for owner review, not an implementation contract.
Date: 2026-09-06. Parent plan:
[Agent, project, and workspace foundation](2026-09-06_agent-project-workspace-foundation.md).
Tracking: `mosaicstack/stack-v2#53`.

Field names, enums, enforcement mechanisms, and storage suggestions in this
file are proposals. Behavior explicitly recorded as an owner ruling is agreed;
exact transition schemas remain proposed. JSON blocks are illustrative records,
not JSON Schemas. Requirements R1-R33 come from the owner discussion in the
parent plan.
Section 2.1 records the 2026-09-06 owner ruling; its field names and hash
mechanics are still proposals, not additional approved schema decisions.
Phase 2 now authorizes detailed drafting and read-only investigation. See the
[Record and operation contract candidate](2026-09-06_foundation-phase2-contract.md).
Adopting a schema or changing runtime behavior still requires later approval.

## 1. Identity and ownership

Proposed rule: stable IDs identify records; display names are editable labels.
Names such as `code-be-01` remain useful to people but are not sufficient to
identify an execution attempt. Use explicit composite references, not a
flattened name such as `agent-project-workspace` that can be misparsed.

| Record | Proposed required information | Owner and scope |
|---|---|---|
| Agent definition | Schema version, agent ID, name, type, harness reference, SOUL reference, role/policy reference, configuration revision | Reviewed shared identity/configuration. No mission progress or project-specific chat. |
| Project | Version, project ID, name, policy reference, revision | Authorized project administration. Contains workspaces; references registered agents. |
| Project registration | Project ID, agent ID, scope role reference and narrowing restrictions, status, revision, granting actor and decision reference | Authorized administrator. Explicit visibility and participation grant, not an agent self-enrollment claim. |
| Workspace | Version, project ID, workspace ID, name, revision, logical file/state references | Authorized workspace administration. Exactly one parent project, confirmed by owner Q5. |
| Workspace registration | Project ID, workspace ID, agent ID, scope role reference and narrowing restrictions, status, revision, granting actor and decision reference | Requires valid project registration. May narrow but not widen it. |
| Mission | Version, mission ID, owning scope, objective, acceptance criteria, status, revision | An authorized work owner. Scope and single-parent relationships are decided in D1; exact fields and lifecycle transitions remain to be specified. |
| Task | Version, task ID, optional mission reference, owning workspace reference, purpose/acceptance criteria, dependencies, status, revision | Work owner sets intent; Q10 permits lightweight assignments without lengthy mission setup. Exact ad-hoc task shape remains proposed. Execution results do not automatically imply acceptance. |
| Assignment | Version, assignment ID, task reference, agent ID, full scope, revision, active claim reference | Work coordinator. Distinct from the reusable agent definition and from one attempt to execute it. |
| Session | Version, session ID, agent/project/workspace IDs, harness session reference, creation mode, predecessor reference when applicable | Workspace-scoped conversation metadata. Scope is immutable. Does not store credentials. |
| Execution | Version, execution ID, full scope, session ID, launch decision, claim ID/generation, start evidence, resolved-context reference, launch/configuration hash references | Runtime-created attempt record. Resume retains session ID but creates a new execution ID. |
| Connection | Version, connection ID, authenticated client actor, session/execution references, observer/controller mode, control generation, admission decision, lifecycle | Proposed representation of Q16. One controlling interface; observation and transfer require permission. Connection is not another agent execution. |
| Context manifest | Version, immutable manifest ID, source references/revisions, selected assignments, resolved skills/policies, prior-session inclusion rule | Launch resolver. Records exactly which approved inputs were supplied. |
| Event | Version, event ID, event kind, subject references, actor/execution identity, observation source, outcome/evidence references | Trusted producer, append-only. An agent's narrative is not execution evidence. |

A field that is optional needs an explicit absence rule in the eventual
schema. Do not use a missing grant to mean unrestricted access, an absent
workspace to mean the last-used workspace, or a missing task to mean any task.
Owner Q10 permits conversation and allowed workspace inspection without a
mission/task, but scope, permissions, and session/execution identity still
apply. Requests to change things become explicit recorded assignments without
lengthy mission setup. Proposed task representation permits no mission reference
for such work, while requiring purpose and acceptance criteria. Missing mission
is not an unrestricted grant. Taskless read/conversation event fields and the
first guaranteed action-audit set remain D11.

Proposed formal-schema requirements:

- Every record has a version; reject unsupported versions and unknown fields.
- References resolve to the intended scope and permitted record version.
- Workspace ID alone is never a sufficient cross-project address.
- Parent and membership status are checked, not just file existence. Owner
  Q5 requires single-parent hierarchy: each workspace has exactly one project;
  each workspace mission has at most one parent project mission, with standalone
  missions still owned by their workspace. Dependencies are separate typed
  references, not parents, ownership duplication, or access grants.
- Display names never authorize access or select paths by themselves.
- IDs and relative paths reject traversal, separators where inappropriate,
  symlink escape, and collisions. Missing targets refuse; do not auto-enroll.
- Changed declarative records create new revisions. Immutable snapshots retain
  the exact revision used by a launch. Authority cannot change through state.
- Final schemas must specify timestamp format, ID generation, uniqueness,
  array limits, status transitions, null/absence rules, and secret exclusions.

### 1.1 Scope permission roles, owner Q26

Use standard permission roles to simplify project/workspace registration, with
registration-specific restrictions that narrow them. Reader, contributor,
reviewer, and coordinator were examples, not an approved role catalog.

A scope role grants operations in the named scope; it does not change the
agent's identity/type or expand reviewed role authority. Grants remain bounded
by agent, project, workspace, mission, and task policy where applicable. Missing
scope membership still refuses access. A reviewer role does not authorize
accepting the holder's own delivery. Grant changes and role-definition changes
are different operations; shared authority changes still require reviewed
commits under repository policy.

Exact role names, permission sets, catalog representation, membership fields,
and enforcement remain D3. Proposed references in section 1 are not an approved
RBAC schema or a new configuration location.

## 2. Launch request and resolved context

Illustrative request for a new conversation continuing established work:

```json
{
  "launchVersion": 1,
  "requestId": "req-001",
  "agentId": "code-be-01",
  "projectId": "mosaic-stack-v2",
  "workspaceId": "sessions",
  "conversation": {
    "operation": "fresh"
  },
  "work": {
    "operation": "continue",
    "assignmentIds": ["assignment-014"],
    "expectedStateRevision": 7
  }
}
```

Names are illustrative IDs. Authentication is not established by this JSON.
The service must attach the verified requesting user/service identity from
the authenticated invocation. A client-supplied actor field cannot grant
permission. `requestId` detects duplicate requests; its exact retry semantics
and storage lifetime remain D8.

Resume instead names `conversation.operation: resume` and an exact `sessionId`,
or uses a documented unambiguous current-session lookup in the same scope.
Owner Q4 ruling: if that scope has never had a conversation, default launch
creates the initial conversation and announces it without an offer. Record
initial creation as distinct from a successful resume. An established session
that is missing or damaged causes an error, not automatic replacement. How
first-use history is established and retained needs a storage/recovery design;
absence of a transcript file alone is insufficient proof of first use.
Fresh allocates a new session ID. Selecting work requires explicit assignment
or task IDs; the exact record fields remain to be specified. Owner Q8 limits
default Abandon to this agent's selected assignments; underlying work remains
unless separately cancelled with authority. Q9 requires an explicit authorized
assignment change before undertaking an unfinished prerequisite, not automatic
addition to the selected work. Authorization can be delegated within the
approved plan under Q7; it need not involve a human prompt for every change.

Proposed launch sequence:

1. Authenticate the requester and validate the entire request.
2. Resolve the agent definition, project, workspace, and both registrations.
3. Check project/workspace visibility and action rights. Derive effective
   authority from the agent ceiling and applicable registrations, mission,
   task, and explicit launch restriction. A lower layer never widens it.
4. Resolve work references and dependencies against the expected state
   revision. State that changed during the decision causes reconciliation or
   refusal, not an unnoticed switch to a different assignment.
5. Resolve Resume/Fresh and any active execution. An active Resume returns the
   Q11/Q15 conflict result or user offer, not another launch. Q17 Fresh requests
   controlled replacement: stop new actions, preserve checked state, resolve or
   identify in-flight effects, and confirm safety before acquiring a new active
   claim. Uncertain safety blocks replacement, never starts competing work.
6. Generate execution-specific inputs and a context manifest. Paths to work
   state come from the selected workspace, never the agent's global seat dir.
7. Persist the launch decision and identity binding before starting work.
   Record a start result separately. Refusal and failed start are not success.
8. Start the program through its reviewed adapter using the exact context.
   Record actual startup and bind its session/process to the execution ID.
9. On exit or interruption, preserve evidence and reconcile active claims.
   A missing completion record means unknown/interrupted, not successful.

These are semantic steps, not a claim that multiple file writes are one
transaction. Crash ordering, claim recovery, and adapter support require
explicit design and tests. They are D7-D9 and D12.

Context content approved in owner Q6, with field layout still proposed:

- Assigned mission and success criteria, current assigned tasks and status.
- Relevant approved project/workspace decisions, not all project history.
- Dependencies, blockers, and references to verified results.
- A proposed next step, visibly distinguished from authorized assignment.
- Unverified notes remain labelled as unverified.
- No old conversation or automatic chat summary for Fresh. Resume retains only
  its authorized conversation; old session IDs may remain as audit references.

Shared governance, identity, and skills still apply through the launch contract.
Owner Q22: user context is not automatically the whole profile. Only explicitly
designated general preferences are shared by default; personal/project-specific
information is supplied where authorized and relevant. Record selected source
references/revisions without copying private content into public metadata.
The exact source/revision representation, context grants, and publishers of
checked state remain schema details. This decision does not change the current
user-context files, dispatch implementation, or install a filtering mechanism.

A generated summary of work can help reading, but cannot replace source
records or convert an agent claim into accepted state. Fresh must not quietly
follow a transcript reference and reload the discarded conversation. Any
intentional historical lookup needs an explicit policy and visible record.

The context manifest should record non-secret source identity/revision,
resolved skill versions, effective policy reference, release/image identity,
harness/provider/model selection, included work, and generation time. Hashes
may bind non-secret content, but do not hash credentials into public records.
Input manifests are execution-specific and write-once; shared prompt scratch
files or per-agent mutable mission files do not meet this proposal.

### 2.1 Canonical configuration and change notices

Owner ruling, 2026-09-06, R16-R17: keep canonical SOUL shared by agent identity,
load the current approved revision on each Resume or Fresh launch, and retain
execution-specific launch inputs. Running instructions are not silently
replaced. All TUI/GUI/WUI clients can reference the launch hash and display a
canonical-versus-running configuration mismatch with a Fresh recommendation.
A new configuration does not automatically restart sessions or abandon work.

Owner Q20: cover shared behavior-affecting agent configuration, not just SOUL.
Included categories are SOUL, shared instructions, applicable enabled skill
versions, harness/model settings, and role configuration. Exclude credentials,
conversation history, and changing task progress. Q21: display automatic,
non-blocking mismatch notices and support on-demand checks. Keep the mismatch
visible without repeated interruption, and make details available. Permission
removal is enforced separately, not delayed behind a Fresh recommendation.

Illustrative notice, wording still for review:

```text
Darkwing / Mosaic Stack v2 / sessions
Agent configuration changed since this session started.
Start Fresh with the current configuration to continue your saved work.
Details: running configuration, current configuration, launch record.
```

Proposed record and comparison mechanics:

- `launchManifestHash` binds the complete non-secret input manifest for one
  execution. It identifies the recorded launch, not the latest desired state.
- `agentConfigHashAtLaunch` identifies the comparable canonical agent
  configuration loaded by that execution, including SOUL content/version.
- A shared status operation returns the execution and launch references,
  stored configuration hash, current canonical configuration hash/revision,
  check time, comparison status, and Fresh recommendation. All clients use
  this operation with the same access checks, not private copies of SOUL.
- Compute both configuration hashes using the same versioned input definition
  and deterministic representation. Q20 establishes included categories; exact
  field/dependency coverage, algorithm, and encoding remain D16. Hash applicable
  shared content, not just its path or unrelated enabled resources.
- Do not compare whole launch manifests for configuration drift: execution
  IDs, timestamps, and workspace/task selections legitimately differ between
  launches. Ordinary work-state changes must not look like base-config edits.
- Do not include secret values or hashes of secrets. Credential refresh and
  selection need their own lifecycle; this notice does not solve #50.
- Status is `matching`, `changed`, or `unknown`. Missing canonical data,
  unsupported hash format, or unverified loaded inputs cannot report matching.
  Never rewrite an old launch hash to make a running session look current.
- Pin a consistent input snapshot before starting the execution. If canonical
  configuration changes during startup, compare against that exact snapshot
  afterward; never label a mixture of two revisions as the loaded state.
- A launch fingerprint describes what was supplied and verified at startup.
  It is not continuous proof that nothing in the process changed afterward.
  Any supported in-process reconfiguration needs a new observed event/status
  model; until then, such changes cannot be represented as verified matching.
- Record comparison observations with execution ID, compared revisions/hashes,
  check time, source, and reason, without exposing private configuration.
  Canonical changes need their own actor/revision record. Notification delivery
  does not count as relaunch or adoption of the new configuration.
- Resume with changed configuration warns that the retained conversation can
  still reflect old instructions. Fresh starts without that conversation;
  adopting the new configuration does not clear the workspace or choose
  Abandon on the user's behalf.

Q21 settles automatic non-blocking notices plus on-demand checking. Transport,
change-detection mechanism, acknowledgement behavior, and notification frequency
remain D16. No polling service is installed or implementation authorized by
this decision. Short hashes may be shown for readability; the full values and
source revisions must remain available through the authorized launch record.
Hashes provide comparison and evidence binding, not permission or proof of
safe behavior. Permission revocation still follows D3 and managed-action
checks; an old launch snapshot is not a right to keep revoked authority.

## 3. State is work data, not authority

Proposed separation:

| Information | How it changes |
|---|---|
| Desired mission, task, membership, and policy | Authorized, versioned changes. Workers cannot elevate grants through progress notes. |
| Observations and decisions | Append-only events with actor, scope, source, and evidence. Corrections reference the earlier event. |
| Current task/project/workspace status | A replaceable current view built from accepted changes, with revision checking and a named writer. |
| Chat transcript | Conversation history, not authoritative task completion or permission. |
| Files produced by work | Mutable working files plus immutable evidence references where needed. A file alone does not prove acceptance. |

Prefer one authoritative copy of project decisions. A launch records the
project revision it saw. Owner Q25 requires reconciliation of affected work
after approved plan changes; an old conversation cannot overrule a newer
approved decision. Revision delivery, impact detection, and stale-action
rejection still need design and tests, including on Resume.

Candidate work states, still for review: `proposed`, `ready`, `active`,
`blocked`, `ready-for-review`, `accepted`, `abandoned`. Completion reported by
an execution can move work toward review, never silently to acceptance by its
own author. Owner Q7 permits an authorized independent reviewer to accept
routine tasks against agreed criteria. Owner-controlled implementation
checkpoints remain separate. Task states, session lifecycle, and execution
outcomes are different fields.

Owner Q8: default Abandon ends this agent's selected assignments. It does not
cancel the underlying shared mission/task or another agent's involvement.
Underlying work remains available for reassignment unless separately cancelled
with authority. Selection preserves source IDs and dependency evidence;
unselected records remain present with explicit status. Owner Q9 requires an
explicit assignment change before undertaking unfinished prerequisite work.
Under Q7, an authorized coordinator can approve that change within the plan
without a human prompt. No silent expansion by the executing worker.
Cross-project selection remains excluded in the initial proposal unless
separately authorized and designed.

Two writers updating the same task need an expected revision and conflict
response. Avoid last-writer-wins. A registration change or permission
revocation during execution must be enforceable at subsequent managed actions,
not only checked once at launch. Owner Q14 requires stopping the affected
workspace executions and blocking further actions there while leaving other
independently authorized work running. Global agent disable is a separate
operation. In-flight effects require reconciliation; stop is not undo. Exact
revocation propagation, stopping, and enforcement mechanisms remain D3/D7.

### 3.1 Delegated autonomy, owner Q7

A software factory needs autonomous decisions within an established goal and
plan. Delegated agents may decompose work and make non-destructive decisions
that advance that goal without seeking user approval each time, provided they
stay within their authority and the plan. An authorized independent reviewer
can accept routine task results against agreed criteria. User approval still
controls declared phase boundaries, plan deviations, and protected operations.

Proposed evidence for each delegated decision: deciding actor/execution,
approved plan revision, delegation reference/limits, affected task/assignment,
reason, and observed result or follow-up evidence. Record the actual delegated
authorizer, not a fictitious owner approval. The acting agent's claim that an
action is harmless is not proof that it is authorized or within scope.

Exact permitted actions, risk checks, and delegation revocation are still D3
and D11. This ruling does not authorize implementation during this interview,
unbounded task expansion, or self-approval of a worker's delivery.

### 3.2 Approved plan changes, owner Q25

Pause affected work when an approved goal, plan, or acceptance criterion changes.
Account for actions already underway rather than assuming they can be undone.
An authorized coordinator may reconcile and adjust assignments within delegated
limits; independently valid, unaffected work may continue. Resume affected work
only after reconciliation. Escalate beyond delegated authority or when safe
resolution cannot be established. An unapproved proposal does not replace the
approved plan or grant authority to continue under new criteria.

Proposed transition evidence: old/new approved revision references, change
approval, affected assignments/dependencies, outstanding-action disposition,
coordinator authority, and resume/reassignment decision. Add evidence rather
than rewriting original launch inputs or historical action records. Exact
fields, publishing/notification paths, impact detection, and stale-revision
fencing remain to be specified under D2/D8/D15.

This differs from a non-blocking shared-configuration mismatch notice under
Q21. An affected assignment must not continue solely because a Fresh launch
has not been requested. Q25 does not require automatic Fresh for every plan
change; context reconciliation and controlled replacement remain distinct.

## 4. Accountability and action evidence

The agent identity remains `code-be-01`. Execution metadata answers which
of its sessions acted, on whose request, within which scope and authority.
This is useful even when no cross-workspace mistake occurred.

Distinguish five things:

1. Requester: the authenticated human/service asking for work.
2. Performer: the reusable agent and the particular execution/session.
3. Producer: the launcher, tool gateway, adapter, or external receipt source
   that observed and recorded an event.
4. Subject: project/workspace, assignment/task, and target of the action.
5. Authority: policy and membership revisions plus any required approval.

### 4.1 Proposed event envelope

```json
{
  "eventVersion": 1,
  "eventId": "event-002",
  "eventType": "action.finished",
  "executionId": "exec-003",
  "sessionId": "session-002",
  "agentId": "code-be-01",
  "projectId": "mosaic-stack-v2",
  "workspaceId": "sessions",
  "assignmentId": "assignment-014",
  "taskId": "task-014",
  "actionId": "action-001",
  "causedByEventId": "event-001",
  "sequence": 2,
  "recordedAt": "2026-09-06T00:00:00Z",
  "producer": "managed-file-tool",
  "operation": "file.write",
  "target": { "relativePath": "notes/result.md" },
  "authorityRef": "decision-003",
  "outcome": "succeeded",
  "evidenceRefs": ["receipt-001"]
}
```

This is a shape example, not a real receipt. `decision-003` would bind the
requester's authenticated identity, full launch scope, current permission
check, claim generation, and any owner approval. The producer fills those
fields from trusted execution context; it does not accept agent-supplied
scope or success statements as evidence. Evidence references must resolve to
accessible immutable records with defined content and provenance.

### 4.2 What counts as an action

Proposed minimum classes to enumerate before implementation:

- Launch/resume/fresh/replacement, refusals, exits, and interrupted executions.
- Mission/task assignment, claim, state change, acceptance, and abandonment.
- Registration/permission changes and explicit owner approvals.
- Managed file/tool invocations, external requests, message send/delivery,
  repository integration, and release operations when these are permitted.
- Usage observations with provider evidence or an explicit estimate label.

Not all of these exist as managed operations today. Adding an enum does not
create interception or enforcement. D11 decides the first guaranteed set.

### 4.3 Intent, effect, and result

Proposed behavior for managed actions with side effects:

1. Persist authorized intent with action ID, target scope, and expected state.
2. Perform the action through the enforcing component.
3. Persist the observed result and evidence, linked to the intent.

Owner Q19: if required intent cannot be persisted, refuse before the action.
If the action may have happened but its result cannot be recorded, block the
affected execution and treat the outcome as unknown. Other executions may
continue only if their own required recording still works. Do not retry
blindly, claim the action never happened, or invent a success receipt.

Owner Q18: an authorized agent/service may investigate using non-destructive
checks within delegated authority. Dependent work resumes only after evidence
resolves the result; otherwise escalate. The original uncertain action must
not be repeated merely as a test. Recovery checks must also satisfy their
applicable permissions and recording requirements, not bypass an audit outage.

Proposed mechanics: distinguish unknown state from observed failure; after
recording is restored, append recovered evidence with its actual observation
and recovery times. Do not overwrite prior events or claim that a record was
written during an outage when it was not. The exact out-of-band failure signal
and recovery receipt format remain D8/D9. External effects and local logging
are not one atomic write.

Use external request/receipt IDs and idempotency support where available.
Without them, an interrupted action may require human reconciliation. A zero
shell exit code only proves that the invoked process reported success; it
does not prove every intended external effect. Clocks are informational;
per-execution sequence and causal references establish local ordering without
claiming a global order across machines.

### 4.4 Coverage and trust limits

A launcher can record process lifecycle. It cannot automatically observe every
file write, child process, network request, or manually entered shell command
inside a running program. A transcript is useful evidence but is neither a
complete action audit nor a trusted authority source.

Each adapter must declare its observable/enforceable operation set. Record
coverage with the execution, for example lifecycle-only versus managed-tool
events. If a requested audit guarantee exceeds support, refuse that launch
mode or require a separately approved limited mode. Never report full coverage
just because the process has an execution ID.

No claim of tamper-proof logging follows from append-only application code.
A worker that can write the evidence directory could forge or remove records.
A trusted producer outside the worker's write permissions is a proposed
requirement for trustworthy managed-action receipts. Storage access and
failure tests must establish it; the current broad data-root mount does not.

Owner Q13 chose concise action records: actor and project/workspace/session/
task, operation, target, authorization, outcome, and evidence references.
Detailed evidence is separate and access-controlled; do not copy full request/
response content into every action event. Neither metadata nor evidence may
contain credentials. Exact safe field lists and evidence retention remain open.

Never put credentials, auth headers, raw environment contents, or arbitrary
unfiltered tool payloads in new audit metadata. Use operation-specific safe
fields and protected evidence references. Redaction failures must not leak
secrets through diagnostics. Define who may view sensitive task/file/message
content; workspace RBAC must apply to audit queries too. Existing transcripts
and run outputs need a separate privacy assessment, not retroactive claims.

## 5. Messages and concurrent execution

Proposed message envelope: version, message ID, sender identity/scope,
authenticated producer, destination agent/project/workspace, optional exact
session/execution/assignment, message kind, causal/reply reference, creation
and expiry times, and body reference with visibility rules.

User-addressed workspace messages may follow the workspace's current authorized
session under a stated policy. Execution results and approvals bind to their
exact execution/assignment revision. A late result must not become an
instruction or approval for replacement work. Ambiguous destinations refuse;
transport delivery and task acceptance are separate receipts.

Owner Q12 permits shared mission/task/decision records and authorized evidence
within a workspace, not blanket access to other agents' conversations. A
transcript needs a separate read permission or explicit authorized handoff.
Neither a shared workspace nor a read grant automatically injects that chat
into another session. Fresh's old-chat exclusion still applies.

Default active limit is one session for each agent/project/workspace tuple.
Owner Q11: an interactive Resume that finds the session already running must
state the conflict and offer to connect, never automatically connect, replace,
or create a duplicate. The owner may already be connected elsewhere. Q15:
a service receives a machine-readable already-active result with the existing
execution identity and must explicitly request connection or another authorized
operation; it does not receive an unanswered interactive prompt.

Owner Q16: one controlling interface connection at a time. Other permitted
connections may observe. Taking control is explicit and requires appropriate
authority; observation does not grant control. Proposed connection records
bind client identity and mode to the exact session/execution. Control-transfer
mechanics must prevent a stale controller from submitting commands after
transfer. Ordinary scoped inter-agent messages are not an implicit controller
connection; their admission/attribution rules remain distinct.

Owner Q17: Fresh requests controlled replacement rather than requiring a
separate stop command. Stop admitting new actions, preserve checked work state,
and settle or identify unfinished effects. Start Fresh only after safe
replacement is established; otherwise stop and report. This is not permission
to replay uncertain actions or import a conversation summary as checked state.
Adapter attachment, control transfer, stop/recovery, and durable claim behavior
must be measured and tested before claiming support.

User tuning changes a limit, not task ownership. Several agents can work in
one workspace but shared files/tasks still need coordination. Proposed active
claims have a unique ID and increasing generation. Managed writers reject
stale generations, so an old process cannot continue after its replacement.
Timeout alone is not proof that an old process has stopped, especially for
unmanaged external actions. Recovery policy is D7.

Budgets and automatic scaling are deferred requirements. Do not place invented
budget defaults into the first schema or imply that recorded usage alone
provides a hard spending limit. The limit scope, approval rights, usage delay,
and response to overruns need a later planning decision.

## 6. Storage constraints, not a migration plan

Keep `<dataRoot>/runs/` as canonical write-once execution evidence. Workspace
views reference evidence there rather than duplicating or rewriting it.
Existing `result.json` records remain untouched. A future version may extend
the record contract through new records and readers, never by rewriting old
runs. New events are append-only and terminal results are written once.

Proposed organization to discuss: projects own workspace metadata/work state;
workspace-and-agent scope owns session references; execution IDs own launch
inputs and receipts. Whether session bytes live in workspace subdirectories
or remain under `<dataRoot>/sessions/` is D6. Logical ownership does not force
a particular filesystem layout. No new storage path is approved by implication.

Every persistent file class needs an owner, writer, reader policy, retention
rule, and recovery rule. Shared agent settings are not a second system config.
Keep secrets in runtime credential storage, not project/workspace metadata.
Do not treat a project directory as permission to edit reviewed role authority.

Current `prune` receipts and data-root `reset` behavior still govern existing
records. The new design must specify dangling references after pruning,
metadata export, reset scope, and recovery before migration. It does not
silently protect new records from reset or authorize a new deletion path.
A safe rollback cannot depend on editing historical evidence.

### 6.1 Workspace retirement and legacy adoption

Owner Q23: closing a workspace retires it from active work. Stop its active
work safely, retain files/history, and prevent ordinary new launches until it
is reopened. This is not deletion or an implicit cancellation of every mission.
Outstanding actions and assignment dispositions need reconciliation under the
existing replacement/recovery rules. Reopening must check current authority;
it must not automatically restore a revoked membership. Those exact transition
records and reopening behavior are still to be designed and reviewed.

Owner Q24: preserve existing unscoped sessions as legacy records. Adopting one
requires explicit reviewed project/workspace assignment. Do not guess from
agent or directory names, place everything in a default project automatically,
or rewrite old execution evidence to pretend it originally had new scope.

Proposed adoption evidence: authorized requester/reviewer, legacy source ID and
non-secret content identity, destination agent/project/workspace, membership
checks, and a new mapping/adoption receipt. This is proposed metadata, not an
approved migration API. Ambiguous lineage or missing access refuses adoption.
Old conversation content remains historical and is not loaded by Fresh.

Actual storage paths, retention intervals, retirement state transitions,
reopening, recovery after prune/reset, and rollback remain D6. Closing does
not exempt records from separately authorized repository retention/reset rules,
and no new deletion tool is approved by the retirement decision.

## 7. Open decisions

| ID | Owner decisions or open question | Remaining proposal or engineering work |
|---|---|---|
| D1 | Scope/hierarchy resolved in Q1/Q5: project owns N workspaces, workspace has exactly one project; a workspace mission has at most one parent project mission or stands alone within its owning scope. Dependencies are not parents. | Formal field definitions and mission lifecycle/completion rules remain to be specified; no multiple-parent ownership. |
| D2 | Recovery content resolved in Q6: assigned mission/criteria, tasks/status, approved decisions, dependencies/blockers, verified-result references, labelled proposed next step and unverified notes; no old chat/automatic summary. | Exact record representation and publisher authority remain schema details; routine acceptance follows Q7/D15. |
| D3 | Q2/Q3/Q14 resolve bounded delegation, scoped visibility, and affected-execution revocation. Q26 chooses standard scope permission roles with per-registration narrowing; they do not redefine agent identity or expand ceilings. | Exact role catalog/grants, record fields, actor authentication, propagation, and stopping need schemas/enforcement. Role names were illustrative; shared role authority remains reviewed-commit controlled. |
| D4 | Resolved by Q4 clarification A: create and announce the initial conversation automatically on genuine first use, without an offer. Later default launches resume; missing/damaged established sessions and ambiguity are errors. | Record initial creation distinctly from resume. Specify reliable first-use history and recovery checks under D6/D8; do not infer first use from a missing transcript. |
| D5 | Default behavior resolved in Q8/Q9: end only this agent's selected assignments on Abandon; undertaking unfinished prerequisites needs an explicit authorized assignment change. | Preserve underlying work/history and other assignments. Q7 allows within-plan delegated authorization without asking the user each time. Fields and interruption sequencing remain open. |
| D6 | Q23 retires closed workspaces safely while retaining files/history and blocking ordinary launches until reopened. Q24 requires explicit reviewed legacy adoption, not inferred membership. | Exact layout, lifecycle/reopening, mapping records, retention intervals, prune/reset reference handling, and migration rollback remain engineering work. Preserve old evidence. |
| D7 | Q11/Q15 require conflict/offer for users and already-active result for services; connection is explicit. Q16 permits one controller plus authorized observers. Q17 requests controlled Fresh replacement, refusing unsafe overlap. | Connection/claim schemas, stale-controller rejection, adapter support, stopping, crash recovery, and concurrency tuning remain engineering work. Timeout alone is not proof an execution stopped. |
| D8 | Q18 permits delegated non-destructive investigation of unknown outcomes, evidence-based continuation, and escalation when unresolved; no blind replay. Exact atomicity/retry guarantees remain open. | Unique requests/actions, linked intent/result/recovery evidence, actual observation times, and explicit unknown status; no blanket exactly-once promise. |
| D9 | Q19 blocks affected executions when required audit recording fails; independently recordable work may continue. Effects with missing result evidence follow Q18 recovery. Storage integrity/trust and failure reporting details remain open. | Refuse before effects; never bypass audit requirements for recovery checks. A trusted writer and out-of-band outage signal need design and tests. |
| D10 | Partly resolved by R16-R17: current approved SOUL at launch, stable per-execution inputs, and cross-interface mismatch notice. Credential sharing and other configuration lifecycle details remain open. | Preserve the owner ruling in section 2.1; reconcile #50 before coding. Exact fingerprint and notification mechanics move to D16. |
| D11 | Q10 permits unassigned conversation/inspection and recorded change assignments. Q13 separates concise metadata from controlled evidence. Q27 A requires command-invocation records with enforced limits, not separate tracing of every internal file/network effect. | Complete taskless/read/chat fields, command/event schemas, evidence allowlists, and enforcement. No isolation, credential, recording, revocation, or recovery gate is waived. |
| D12 | Phase-2 inspection of documentation extracted from the pinned image establishes documented exact-session selection, RPC/JSON events, queue/abort distinctions, and no built-in sandbox. Current Mosaic adapter uses plain print/native TUI instead. | No live RPC, hook, controller, or isolation test yet. Investigate the enforcing integration and failure behavior; host Pi 0.85.1 is not evidence for runtime 0.84.4. |
| D13 | Q12/Q13 separate shared work records, transcript grants, and controlled audit evidence. Q22 shares only designated general preferences by default and supplies personal/project context only where authorized and relevant. | Exact context classification/grants and enforcement remain to be specified. Read permission does not imply automatic transcript loading; replace blanket global user-context injection only through approved implementation. |
| D14 | Jason answered Q28 A: a Mosaic-controlled terminal backed by Pi is acceptable. R34 records this; native UI parity is not an initial requirement. | Runtime/control/input schemas and shared operations now form an owner-review candidate. No UI implementation, engine replacement or safety waiver follows. |
| D15 | Q7 allows authorized independent routine acceptance and delegated non-destructive within-plan decisions. Q25 pauses affected work after approved plan changes, permits delegated reconciliation, and lets independently valid unaffected work continue. | Preserve owner checkpoints and plan-deviation/protected-operation approval. Readiness writers, impact detection, stale-action rejection, conflicts, and change evidence remain open; workers do not self-accept. |
| D16 | Q20 covers shared behavior-affecting config: SOUL, instructions, applicable enabled skills, harness/model settings, and role config, excluding credentials/chat/task progress. Q21 requires automatic non-blocking notices and on-demand checking. | Exact hash/dependency fields, encoding, snapshot verification, delivery/acknowledgement, and frequency remain technical details. Separate comparable config from whole launch identity; no silent refresh. |

The owner authorized a grill-me interview on 2026-09-06. Ask each round's
questions only after their prerequisites are settled. Record answers without
silently resolving qualifications. Independent analysis later may add questions
or reject recommendations, not overwrite owner rulings.

### 7.1 Owner interview record, round 1, 2026-09-06

Source: Jason's answers in pi session
`01a06e48-0718-71f2-a889-c263c4800fb9`. Interview Q numbers are separate from
D decision IDs. This records partial alignment, not full design approval.

- Q1, D1: "c. Glad you thought of that answer too." Option C permits both
  project and workspace missions with explicit links, including standalone
  workspace missions within project scope. Each has one authoritative owner.
- Q2, D3: "B". User delegates bounded authority for system registration and
  assignments. Outside-limit actions require approval, not agent self-grants.
- Q3, D3: "B". Project membership gives shared project information plus
  explicitly permitted workspaces, not visibility into all workspace content.
- Q4, D4, verbatim: "B, I'm not sure the offer is necessary. A declaration of
  initial conversation instantiation is good, but an offer on a non-existent
  item is unnecessary." The no-offer preference is clear. First-creation
  behavior needs a focused clarification before the command rules are settled.

Q4 clarification, 2026-09-06: Jason answered "A" to automatic first creation
with an announcement and no offer. Later launches resume by default; Fresh
explicitly starts a new conversation. Missing or damaged previously established
conversations are errors rather than first-use cases. This resolves the
qualification above without rewriting the original answer.

Next: continue mission relationships, Fresh recovery, completion authority,
and work-selection decisions. Do not treat an unanswered question or an
interview recommendation as an owner decision.

### 7.2 Owner interview record, round 2, 2026-09-06

Source: Jason's answers in the same pi session as round 1. Previous answers
remain recorded above; this is not full plan/schema approval.

- Q5, D1: A, with the owner qualification that parent:child relationships
  stay strictly one-to-many. A project has N workspaces; each workspace requires
  exactly one parent project. A workspace mission has at most one parent
  project mission as proposed in Q5. Dependencies are different from parents.
- Q6, D2: "agreed" to the full proposed Fresh/Continue information set:
  mission/criteria, assigned tasks/status, approved decisions, dependencies,
  blockers, verified-result references, labelled proposed next step, and
  labelled unverified notes. Old chat and automatic summaries stay out.
- Q7, D15/D3: B. Authorized reviewers may accept routine tasks. Jason clarified
  that a software factory needs autonomous goal-directed decisions, layered
  decomposition, and delegated non-destructive actions within the established
  plan without user interaction each time. Deviation does not inherit that
  authority. The agreed user implementation checkpoints remain in place.
- Q8, D5: A. Default Abandon ends this agent's selected assignments; missions
  and tasks remain for reassignment unless separately cancelled with authority.
- Q9, D5: B. Show an unfinished prerequisite and obtain an explicit assignment
  change before doing it; include relevant dependency information, not silent
  extra work. Read with Q7: the authorizer may be a delegated coordinator, not
  necessarily the user. Record the assignment change and its actual authority.

Next questions concern review separation with reused agent identities,
unassigned interaction, revocation, concurrency conflicts, and audit behavior.
No downstream recommendation is settled by the answers above.

### 7.3 Owner interview record, round 3, 2026-09-06

Source: Jason's answers in the same pi session as rounds 1-2. No full schema
approval or implementation authorization is implied.

- Q10, D11: A. Permit conversation and authorized workspace inspection before
  a mission/task exists. Requests to change things become explicit recorded
  assignments without requiring a lengthy setup process.
- Q11, D7/D14: owner correction to the automatic-connect recommendation.
  State the active-session conflict and offer connection because the user may
  already be connected and have forgotten. Owner example, verbatim:
  "I see that session is aalready active. Would you like to connect?"
  No automatic connection or duplicate launch. Non-interactive service
  response was not specified by this answer and remains open.
- Q12, D13: B. Shared work records and permitted evidence, but another agent's
  conversation needs a separate permission or explicit handoff. Read access
  does not imply automatic loading into the receiving conversation.
- Q13, D11/D13: A. Concise action metadata and evidence references; detailed
  evidence separately controlled, not copied wholesale into each audit event.
  Credentials must not appear in either.
- Q14, D3/D7: A. Workspace membership removal stops affected executions and
  blocks further actions there; other independently authorized work continues.
  Global agent disable is separate. Reconcile effects already in flight.

Next: clarify service-side conflict handling and decide connection ownership,
replacement, uncertain-action recovery, and audit-failure behavior. Technical
capability checks must supply facts, not be questions the owner must guess at.

### 7.4 Owner interview record, round 4, 2026-09-06

Source: Jason answered A to each of Q15-Q19 in the same pi session as prior
rounds. These settle behavior, not unmeasured runtime capabilities.

- Q15, D7/D14: service receives an already-active result with execution identity
  and explicitly requests any authorized connection/next operation. No automatic
  attachment or interactive offer waiting for a nonexistent human response.
- Q16, D7: one controlling interface connection; other authorized connections
  may observe, with explicit control transfer and conversation access checks.
- Q17, D7: Fresh requests controlled replacement. Stop new actions, preserve
  checked state, settle or identify unfinished actions, and only replace safely.
  If safety cannot be established, stop/report rather than overlap executions.
- Q18, D8: delegated authorized agents/services may investigate unknown results
  with non-destructive checks. Resume dependent work only on resolving evidence;
  otherwise escalate. Repeating the uncertain action is not a recovery test.
- Q19, D9: audit-recording failure blocks affected executions. Other work may
  continue only when its required recording works. Refuse before effects, and
  reconcile effects already issued whose results could not be recorded.

Next: configuration fingerprint scope/notices and workspace retention/migration
choices. Exact schema and runtime mechanisms remain unapproved until examined;
no implementation or broader phase advancement follows from these answers.

### 7.5 Owner interview record, round 5, 2026-09-06

Source: Jason answered Q20 B, Q21 B, Q22 B, Q23 A, Q24 A in the same pi session.
These are behavior decisions, not permission to change runtime configuration.

- Q20, D16: shared behavior-affecting configuration fingerprint, not SOUL only.
  Include SOUL, shared instructions, applicable enabled skill versions,
  harness/model settings, and role config. Exclude credentials, chat, and task
  progress; revocation remains an enforcement event, not merely a notice.
- Q21, D16: automatic non-blocking notices plus on-demand checks; keep mismatch
  visible without repeated interruption or automatic restart.
- Q22, D13: designated general preferences may be shared; personal and project
  information is scoped by authorization and relevance, not a blanket profile.
- Q23, D6: close means retire from active work, stop safely, retain files and
  history, and block normal launches until reopened. Cleanup/deletion is separate.
- Q24, D6: preserve legacy sessions, then explicitly review and assign their
  project/workspace on adoption. Do not infer membership or auto-place them.

Next behavioral questions concern changes to an approved plan during execution
and how scope permissions are expressed. Engineering questions remain open for
fact-finding and schema review, not guesses or silent implementation decisions.

### 7.6 Owner interview record, round 6, 2026-09-06

Source: Jason answered Q25 A and Q26 B in the same pi session.

- Q25, D15: pause affected work after an approved plan change and reconcile
  underway effects and assignments. A delegated coordinator can adjust work
  within its limits; unaffected work may continue. Escalate beyond authority
  or when safe resolution is unavailable, rather than finish obsolete work.
- Q26, D3: standard scope roles with registration-specific narrowing. A scope
  role describes permission there, not agent identity/type. Exact names and
  grant lists remain subject to review; no expanded agent ceiling is implied.

### 7.7 Interview checkpoint, confirmation pending

Q1-Q26 have answers, with qualifications retained above, including the explicit
Q4 correction. No additional owner-behavior question is currently ready. Ask
Jason to confirm shared understanding of R1-R32; do not equate these individual
answers with interview completion or approval of the whole schema.

D1-D16 retain unresolved engineering questions: fields and record lifecycles,
authorization/enforcement, work-state revisions and recovery, adapter/session
capabilities, observable action coverage, storage/migration, configuration
hashing/notification, and concrete command/UI contracts. Detailed design and
fact-finding need next-phase authorization. Technical findings that introduce
new behavioral tradeoffs come back to the owner, not silent design decisions.

No mapping, independent gap analysis, implementation, migration, commit, push,
or issue closure follows automatically from this interview checkpoint.

### 7.8 Owner confirmation of intended behavior, 2026-09-06

Following round 6 and the assistant's behavior summary, Jason replied:
"That looks correct." This confirms shared understanding of intended behavior
represented by R1-R32. Section 7.7 records the preceding pending checkpoint;
its confirmation request is now satisfied.

This confirmation does not approve exact schemas, establish runtime support,
or resolve the remaining engineering branches. Phase 2, detailed design and
read-only technical investigation, still requires explicit authorization.
Mapping, independent gap analysis, implementation, migration, commit, push,
and issue closure remain outside current authority.

### 7.9 Phase-2 authorization and first investigation, 2026-09-06

Jason answered yes to detailed records, permissions, commands, and audit
guarantees with read-only technical investigation. This supersedes the pending
authorization recorded in section 7.8. Mapping, implementation, migration,
publication, and issue closure remain outside authority.

The linked phase-2 candidate records tool-free source-analysis run
`r-20260906T024609Z-68ee7f`, pinned image/document identities, author
qualifications, proposed common types, operation rules, and remaining work.
The run is investigative output, not independent gap analysis or approval.

Q27 is now ready for the owner: accountable command invocation with enforced
limits and controlled evidence, or separately attributable internal file/network
effects before command execution is enabled. Recommendation A is recorded in
the candidate; no answer or added approved requirement is inferred.

### 7.10 Owner Q27 ruling, 2026-09-06

Jason answered "Q27: A". Initial managed command auditing records the authorized
invocation, actor/scope/assignment, enforced filesystem/network limits,
start/end, outcome, and controlled evidence references. It does not require
separate enumeration of every internal file read/write or network operation.

This settles the question left pending in section 7.9 and adds R33. Workspace
isolation, credential protection, fail-closed recording, revocation, and
uncertainty recovery remain required. Exact schemas and enforcing mechanisms
are still phase-2 work; this is not implementation or mapping approval.

### 7.11 Resumed goal and Q28 frontier, 2026-09-06

After reboot recovery, Jason explicitly set the phase-2 goal and repeated it
with --wait-timeout 60. This resumed the existing planning assignment, not a
second goal or an implementation mandate. No exposed goal runtime API or
automatic timeout/wake has been verified; CURRENT records file-based state.

The linked phase-2 package now has checked command/record schemas, negative
fixtures, explicit calendar/path checks, restricted-domain fingerprint vectors,
and permission/reference/lifecycle/storage and #50 compatibility proposals.
These are author design checks, not independent review or runtime enforcement.

Q28 is ready: may the first managed release use a Mosaic-controlled terminal
client, or must it preserve the native Pi terminal with full control mediation?
Recommendation A is recorded in the package. No answer is inferred. Runtime
execution/control/input-routing and command artifact contracts depend on that
choice; manual owner response is the next resumption condition.

### 7.12 Owner Q28 ruling and goal clarification, 2026-09-06

Jason answered "Q28: A". R34 records the managed-terminal ruling. The author
continued P2-5/P2-6: closed runtime/control/artifact shapes, synthetic rule checks,
and the owner-review package. The prior Q28 wait in section 7.11 is historical.

Jason also clarified that /goal came from the separate ~/.mosaic deployment and
is not implemented in this development environment. Continue the same goal through
the existing repository records; no extension installation or active wait timeout
is requested. Goal completion still requires Jason's phase-2 verdict.

[Owner review and D1-D16 reconciliation](foundation-v1-candidate/REVIEW.md) is the
current candidate index. Runtime security/enforcement and later phase approvals
remain separate from the author checks. Earlier open-detail descriptions above
are preserved as the interview/design history, not claims of implemented behavior.

## 8. Trace checklist for the later independent analysis

The non-authoring agent must trace, at exact code and plan revisions:

- Request authentication -> registrations -> effective permissions.
- Workspace selection -> authoritative state -> context manifest -> program.
- Resume/Fresh choice -> exact session -> unique execution -> active claim.
- Existing-session conflict -> authorized connection -> sole controller or
  observer -> explicit control transfer -> stale-controller refusal.
- Canonical configuration -> stable launch inputs/hash -> running execution
  status -> shared comparison -> TUI/GUI/WUI notice -> authorized relaunch.
- Assignment -> action authorization -> side effect -> intent/result evidence.
- State update -> revision conflict handling -> visible task/project status.
- Message address -> permission check -> execution-aware delivery -> receipt.
- Exit/crash -> uncertain effects -> recovery -> replacement permission.
- Audit query -> scoped visibility -> retention/prune and recovery behavior.

For each connection: cite the actual implementation or explicitly record it
as missing; cite the approved plan requirement; name the writer/enforcer and
the receipt; identify unsupported guarantees and a reproducible test. Separate
implementation gaps from holes or contradictions in the plan. Do not fix the
candidate during review or substitute the map author's assurances for evidence.

The independent report and Archify maps are later deliverables. This file
contains no independent verdict and no assertion that these controls exist.