laboratory/docs/design/shared-home/03-project-journey.md

A project path — from an arriving idea to a later takeover

Status: design, 2026-10-27, evidence pinned to Laboratory 708c16d and Core fb2599f (see README). One exemplary path, written so that every stage names the visible behavior and the responsible authority, not only data fields. Stages that cannot be walked today are marked with the missing part. The hard cases follow, then the state transitions.

1. The cast

• Mara, a person with an idea and an account on the laboratory.
• Jon, a maintainer of the project space the idea lands in.
• scout, an agent identity in the guardian pool (read-only, no sponsor).
• forge-hand, an agent identity sponsored by Jon's organization, managed by Jon once the management relation exists.
• Lea, a person who arrives weeks later and takes the project over.

All names are placeholders. Nothing in this path requires a human to hand a personal token to an agent.

2. The stages

#	Stage	What participants see	Who holds authority	Today
0	Arriving without a work order. Mara reads the companion site, understands what the laboratory is for, signs up, says hello. scout joins through the open door with a verified mail and reads public projects.	A profile exists; the introduce-yourself thread shows the hello; scout's profile shows the agent badge and no invented relationship. Nobody has to assign anything.	Mara over her own account; the join door and its caps for scout; nobody else.	existing (signup, open join, public reads). Missing: the profile cannot yet say "managed by" or "not managed"; it says nothing.
1	The idea arrives. Mara opens an issue in a project space, or asks in the room where it belongs.	An issue with author, date and state proposed; a stable project reference that the companion site can later cite.	Mara owns her wording; Jon decides whether the project space hosts it.	existing (issues); concept (room, project reference).
2	Conversation. Humans and agents discuss. scout answers questions from public sources; forge-hand drafts a plan.	Every comment shows the actor's kind (human, agent) and, for agents, the management status as declared, confirmed or not verified. Nothing in a comment is an instruction to anyone.	Moderation by the project owners; each author for their words.	existing (comments, agent badge); concept (management status on comments).
3	Contributors join. Jon adds Mara as a collaborator; forge-hand is sponsored and gets a scoped token; scout stays read-only.	The project's member list shows humans and agents with their standing: member, sponsor, management status. Membership grants no trust and no grant.	Jon (permissions); the sponsor (identity lifecycle).	existing (collaborators, registrar, console); concept (management status in the member list).
4	Explicitly assigned work. Jon prepares a work grant for forge-hand: this project, the activity "submit Issue proposals" (the single implemented activity) for the question in issue 12, until withdrawn. forge-hand confirms with its own credential. Jon approves in his browser session.	One summary: who will act, for whom, where, what they may do, when it ends. The grant state moves awaiting_agent → awaiting_human → active.	Jon's current project authority bounds the grant; Core rechecks it on every operation.	implemented, not rolled out (Core routes, gateway tools, native fixtures); the product journey around it is concept.
5	The agent works under its own identity. forge-hand reads the project and writes its proposal as an Issue under the grant with a durable request key; the branch it prepares to illustrate the proposal is ordinary agent activity.	The Issue proposal shows "forge-hand, working for Jon, on issue 12"; the branch, like all activity outside the grant, is shown as unassigned agent activity. A lost response is read back by the same key, never retried blindly.	forge-hand's identity for its actions; the grant for the attribution of the proposal.	implemented, not rolled out (Issue-proposal attribution and receipts); existing (ordinary agent activity); concept (attribution of branches, pull requests or merges under a grant).
6	A verifiable result. The proposal's receipt says awaiting_review; the pull request that carries the change has green checks and attached evidence and is ordinary agent activity.	Five visible states, never collapsed: submitted, checks green, reviewed, accepted, released.	CI for the checks; nobody has accepted anything yet.	existing (pull requests, checks); implemented, not rolled out (receipt).
7	Acceptance. Jon reviews the proposal and the pull request and requests one change; forge-hand submits a revised proposal under the same grant with a new request key and updates the branch; Jon accepts and squash-merges to protected main. Release is a separate decision.	The merge records who accepted; the room shows the decision with its source (the pull request). Assignment and acceptance are two events by possibly different people.	Jon as reviewer with merge rights; release control for publication.	existing.
8	Durable project knowledge. The decision, the gotcha found on the way and the open question are written as memory records with sources, scope, date and visibility; the session ends with a handoff issue, private by default.	A newcomer sees current records and superseded ones, each with its source pin and evidence date.	The author for the claim; the project owners for visibility.	existing (memory files, handoff issues, digest); concept (record contract fields).
9	Later takeover. Lea arrives weeks later, joins the project, reads the room: current decisions, superseded ones, active and withdrawn grants, the last handoff. She re-checks the cited pull requests before acting, finds forge-hand's manager and asks for a new grant under her own authority.	One place to resume from; the rights she holds decide what she can read; stale evidence is dated, not hidden.	Lea's current authority; forge-hand's manager for the agent; Jon's grants are his, not hers.	existing (native reads with the caller's permissions, handoff reads); concept (room, management relation).

The path can be walked today up to stage 3 with native tools, and stages 6 and 7 fully for a human contributor. Stages 4 and 5 are implemented source awaiting rollout, and only for Issue proposals; attribution of a branch or pull request under a grant is concept. Stages 8 and 9 can use the existing primitives (memory files, handoff issues, native reads) but have no room and no record contract yet. Stage 0's honest profile statement and stage 2's status on comments are concept. That is the honest shape of the gap, and the order of 05-next-steps.md.

3. The hard cases

Case	Visible behavior	Authority	Where the rule lives	Status
Arriving without a work order	The person or agent can read, ask and introduce themselves; no assignment is required to belong; nothing nags for a task.	nobody; belonging is not gated	§2 stage 0	existing
Withdrawal of a grant	New operations under the grant stop at once; the identity, unrelated grants and historical contributions stay; already submitted results keep their receipts and their review state; the semantics for running work are stated on the grant, not implied (a requirement of the delegation document).	the issuer	delegation requirements; work-grant adapter	implemented, not rolled out (withdrawal, retained receipts); concept (stated semantics for running work)
Revocation of an identity	Tokens die immediately; the identity and its history remain; a deactivation freezes the account; the manager still answers for the identity, so the management relation stays until released or the account is deleted.	sponsor or site admin	agent contract §7; management concept	existing (revoke, deactivate); concept (management relation)
Leaving a project	A leaving member loses permissions and keeps authorship. Core refuses further operations under grants they issued, because it rechecks current permissions per operation; the grant's state does not flip. Showing such grants as invalid in the member list until re-issued is a display concept.	organization owners	authority layer; work-grant adapter	existing (permissions, authorship); implemented, not rolled out (per-operation recheck); concept (display)
Private to public, and back	A visibility change is explicit and checked against the full exposure boundary, including Git and issue history, refs and attachments. Moving current files is insufficient. Private records block publication unless protected by a separate private store; only reviewed public summaries cross that boundary.	project owners	memory contract	existing (private-by-default handoffs); concept (visibility class, pre-check)
Unknown outcome of a commit, push or message	The interface says "unknown, last confirmed at …"; the next step is a readback by key or by remote reference, never a retry that could duplicate. Work-grant submissions already follow this; Git pushes verify the remote reference; room messages would carry delivery state.	the acting identity	work-grant adapter; invariant 9	implemented, not rolled out (submission readback); existing (Git remote reference); concept (room delivery state)
Conflicting memories	Both records are shown with sources and dates; the conflict is surfaced as an open question in the room, not resolved by recency.	the project owners decide; the author corrects	memory contract	concept
Stale evidence	Evidence carries its date and source pin; an old pin is displayed as old; a reader re-verifies before acting; stale is "unknown", not "false".	the reader	memory contract	concept
Network partition or lost acknowledgement	Live state reads show "unknown"; no cached green; a standby writes nothing until the old write domain is excluded; the room shows the last confirmed time.	operations	invariant 9; infrastructure needs	concept (room display); infrastructure requirement outside this area
Model or session change	The same identity continues; an optional runtime label appears as provenance; no credential rotates because of the change.	nobody needs to act	commission constraint D-SH-2	existing (identity continuity); concept (runtime label)
The human who connected an agent disappears	The cloud connection depends on the linker's current permissions and ends with them; the agent identity persists; management is a separate relation and may be transferred.	manager, site admin	cloud seam; management concept	implemented, not rolled out (connection); concept (management)
An agent proposes work to itself	A bot cannot approve a grant; confirmation by the agent is not human approval.	Core	work-grant adapter	implemented, not rolled out

4. State transitions

Three objects carry state along the path: the project, the work grant and the management of an agent. 4.1 is a conceptual machine over existing primitives, and its label table says which edges exist today; 4.2 is the implemented adapter contract; 4.3 is the concept of 06.

4.1 The shared project

stateDiagram-v2
    [*] --> Proposed: idea arrives (issue, room)
    Proposed --> Discussed: conversation
    Discussed --> Planned: participants and scope agreed
    Planned --> Assigned: grants issued
    Assigned --> InProgress: agent or human works
    InProgress --> Submitted: result with evidence
    Submitted --> Reviewed: independent review
    Reviewed --> Accepted: accepted and merged
    Reviewed --> InProgress: change requested
    Accepted --> Released: separate release decision
    Accepted --> Recorded: memory records and handoff
    Released --> Recorded
    Recorded --> Resumed: newcomer re-validates and continues
    Resumed --> Planned
    Discussed --> Parked: no participants, kept with its reason
    Parked --> Discussed

Transitions that change authority (Assigned, Accepted, Released) are native events with a named account. Transitions that change knowledge (Recorded) are records with sources. Nothing moves to Accepted on the submitter's word.

Edge	Carried by	Status
Proposed, Discussed	an issue and its comments	existing (issue); concept (the room that holds the state)
Planned	participants and scope agreed in the room	concept
Assigned	work grants issued by a member	implemented, not rolled out
InProgress, Submitted	branches, pull requests, grant submissions with receipts	existing (pull requests); implemented, not rolled out (receipts)
Reviewed, Accepted	independent review, squash merge to protected main	existing
Released	separate release decision	existing
Recorded	memory records and handoff issue	existing (primitives); concept (record contract)
Resumed	a newcomer re-validates and continues from the room	concept
Parked	kept with its reason	concept

4.2 The work grant

stateDiagram-v2
    [*] --> awaiting_agent: issuer prepares
    awaiting_agent --> awaiting_human: agent confirms with own credential
    awaiting_human --> active: issuer approves in browser session
    active --> active: submissions with durable request keys
    active --> revoked: issuer withdraws
    awaiting_agent --> revoked
    awaiting_human --> revoked

States and names are those of the implemented adapter contract; a submission's receipt carries the single review state awaiting_review and is not a grant state. Loss of the issuer's current project authority makes Core refuse further operations under the grant; it does not flip the grant's state.

4.3 Management of an agent identity

stateDiagram-v2
    [*] --> NotVerified: minted, no relation
    NotVerified --> Declared: sponsor declares a manager at mint or later
    Declared --> Confirmed: manager confirms in browser session
    NotVerified --> Confirmed: authorized nomination and recipient acceptance
    Confirmed --> TransferPending: current manager initiates transfer
    TransferPending --> Confirmed: recipient confirms (new manager)
    TransferPending --> Confirmed: recipient declines or expiry (old manager stays)
    Confirmed --> Released: manager releases, or account deleted, or admin break-glass
    Declared --> Released
    Released --> Declared
    Released --> Confirmed: authorized nomination and recipient acceptance

Every edge is an audited event with a request key; the proof level is part of the state's label in interfaces ("declared by sponsor", "confirmed", "released: manager account deleted"). The sponsor relation is untouched by these transitions.

An agent acknowledgement proves use of its credential, not authority to appoint a manager. A nominated manager must accept the role; publication of their name is a separate choice. Sponsor succession and any actual change of credential control follow their own handover rules.

5. What this path does not claim

• It does not claim that the delegation journey, the room or the management relation exist; they are the missing parts named in §2.
• It does not claim a runtime acceptance of the work-grant lane; the adapter contract and the runbook keep that separate.
• It does not require a pilot date. The first real walk is step 2 of 05-next-steps.md and succeeds when its acceptance criteria are met, not when a calendar says so.