chore: establish signals feature baseline

2026-07-23 14:29:57 +05:30
parent aa1c89a310
commit 52510d1107
10 changed files with 433 additions and 5 deletions
--- a/docs/2026-07-23_140325-signals-backend.md
+++ b/docs/2026-07-23_140325-signals-backend.md
@@ -0,0 +1,420 @@
+# Signals Backend Implementation Plan
+
+> **For OMP:** Create one isolated task worktree per implementation task. Run dependent tasks serially, merge each completed task branch into `feat/signals`, resolve integration conflicts on that branch, and verify the merged result before dispatching the next dependent task.
+
+**Goal:** Build the first product-grade Signal slice: the authenticated global agent turns one or more exact user messages into one durable, Effect-modeled Signal containing immutable raw evidence and a separate processed problem statement.
+
+**Architecture:** Keep the Signal domain pure in `@code/primitives`; keep authorization, idempotency, storage, and source resolution in Convex; keep conversation transport and the agent decision in Flue. The global Zopu agent becomes organization-scoped and receives two narrow tools: list eligible user-message sources, then create a Signal from selected message IDs and a processed problem statement. AgentOS remains downstream execution infrastructure and is not involved in Signal capture.
+
+**Tech Stack:** Bun workspaces/catalogs, TypeScript, Effect v4, Convex, Flue, Hono, Better Auth, Vitest, convex-test.
+
+---
+
+## Current findings and decisions
+
+1. `PRODUCT.md` separates **Signal**, **Candidate Work**, and **Work Unit**. This slice must not create candidate, plan, priority, run, or execution fields.
+2. `TECH.md` requires explicit organization scope, exact user-message persistence, raw-evidence/agent-interpretation separation, and source links.
+3. The current global chat is `zopu/main`, so every user shares one Flue instance. Flue routes are pass-through and the browser sends no identity. This must be corrected before Signals can be safe.
+4. Canonical Flue `user_message` records already contain exact text plus `messageId`, `conversationId`, timestamp, and `submissionId`, but Convex stores them inside opaque JSON batches. Product commands should not parse those batches ad hoc.
+5. Existing `projectSignals` is an execution event feed, not the product Signal entity. Rename it to `projectEvents` before introducing `signals`.
+6. The Signal primitive will use Effect schemas and a pure Effect constructor. It will not contain a repository service or depend on Convex, Flue, Hono, AgentOS, or generated IDs.
+7. A Signal is created only when the global agent decides the conversation contains a coherent problem statement. Individual user messages remain conversation evidence until then.
+8. One Signal may compose multiple ordered user messages. Raw text remains per-message and exact; `problemStatement` is the agent-produced interpretation.
+9. Signal creation is idempotent by organization + conversation + ordered source-message IDs so Flue retries cannot create duplicates.
+10. Use a minimal organization foundation because `ownerId` is a user identifier, not the hard tenancy boundary required by the product. Do not build full organization administration in this slice.
+
+## Domain model
+
+```ts
+interface Signal {
+  readonly id: SignalId;
+  readonly scope:
+    | { readonly _tag: "Organization"; readonly organizationId: OrganizationId }
+    | {
+        readonly _tag: "Project";
+        readonly organizationId: OrganizationId;
+        readonly projectId: ProjectId;
+      };
+  readonly sourceMessages: readonly [SignalSourceMessage, ...SignalSourceMessage[]];
+  readonly problemStatement: ProblemStatement;
+  readonly processedBy: {
+    readonly agentName: string;
+    readonly agentInstanceId: string;
+  };
+  readonly createdAt: TimestampMs;
+}
+
+interface SignalSourceMessage {
+  readonly conversationId: ConversationId;
+  readonly messageId: ConversationMessageId;
+  readonly rawText: string; // exact; never trim or rewrite
+  readonly createdAt: TimestampMs;
+}
+
+interface ProblemStatement {
+  readonly title: string;
+  readonly summary: string;
+  readonly desiredOutcome: string;
+  readonly constraints: readonly string[];
+}
+```
+
+**Invariants:**
+
+- Every Signal has exactly one organization scope and zero or one project scope.
+- `sourceMessages` is non-empty, ordered, and unique by `(conversationId, messageId)`.
+- Every source is a user message from the same organization-scoped global conversation.
+- `rawText` is copied server-side from the stored source message; the agent never supplies it.
+- `problemStatement.title`, `summary`, and `desiredOutcome` are non-empty; constraints are structured as individual non-empty items and remain distinct from raw evidence.
+- Signal does not contain candidate/work-unit/run fields.
+- IDs are branded non-empty strings in primitives; adapters translate Convex/Flue IDs.
+- Timestamps are non-negative integer epoch milliseconds.
+
+## Persistence model
+
+Add these application tables in `packages/backend/convex/schema.ts`:
+
+- `organizations`: minimal durable tenant record with `name`, `createdBy`, `createdAt`.
+- `organizationMembers`: `organizationId`, `userId` (`identity.tokenIdentifier`), `role`, `createdAt`; indexes by user and organization/user.
+- `conversationMessages`: normalized user-message evidence with `organizationId`, `conversationId`, `messageId`, `submissionId?`, `clientRequestId`, `role: "user"`, exact `rawText`, `status: "admitting" | "admitted" | "failed"`, and `createdAt`; unique lookup indexes by organization/message and organization/client request.
+- `signals`: `organizationId`, optional `projectId`, `sourceKey`, structured `problemStatement` (`title`, `summary`, `desiredOutcome`, `constraints`), `processedByAgentName`, `processedByAgentInstanceId`, `createdAt`; indexes by organization/createdAt, project/createdAt, and organization/sourceKey.
+- `signalSources`: `signalId`, `organizationId`, `conversationId`, `messageId`, `ordinal`, `rawTextSnapshot`, `sourceCreatedAt`, optional `submissionId`; indexes by signal/ordinal and organization/message.
+- `projectEvents`: the renamed current execution event feed.
+
+Do not add lifecycle/candidate status to `signals` yet. A later Candidate component will own promotion and relationships.
+
+---
+
+### Task 1: Normalize the workspace dependency catalog
+
+**Objective:** Centralize every dependency repeated across workspace manifests without forcing intentionally different platform versions into one range.
+
+**Files:**
+
+- Modify: `package.json`
+- Modify: `apps/daemon/package.json`
+- Modify: other `apps/*/package.json` and `packages/*/package.json` entries identified by the catalog audit
+- Modify: `bun.lock` through `bun install`
+
+**Steps:**
+
+1. Add default catalog entries for shared versions that should converge: `effect`, AgentOS packages, `typescript`, `@types/bun`, `@types/react`, `heroui-native`, `vite`, `vitest`, and `convex-test`.
+2. Add named catalogs for intentional platform splits, especially Node type majors and React/React Native compatibility ranges. Use `catalog:<name>` rather than silently upgrading Expo/native consumers.
+3. Replace direct Effect and AgentOS pins in `apps/daemon/package.json` with `catalog:`.
+4. Replace repeated direct versions in workspace manifests with their default or named catalog reference. Leave peer dependency compatibility ranges as peer ranges when they intentionally describe supported versions rather than installation versions.
+5. Run `bun install` and verify the lockfile resolves the same intended platform families.
+
+**Acceptance:**
+
+- No repeated installed dependency version remains scattered across manifests without an explicit reason.
+- Effect v4 and AgentOS resolve from the root catalog everywhere.
+- Native React remains on its Expo-compatible exact family; web/TUI ranges are not accidentally collapsed.
+
+**Verification:**
+
+```bash
+bun install
+bun run check-types
+```
+
+---
+
+### Task 2: Add the pure Effect Signal primitive
+
+**Objective:** Establish the portable Signal vocabulary and validation rules before storage or agents depend on it.
+
+**Files:**
+
+- Create: `packages/primitives/src/signal.ts`
+- Create: `packages/primitives/src/signal.test.ts`
+- Modify: `packages/primitives/src/index.ts`
+- Modify: `packages/primitives/package.json`
+
+**Implementation:**
+
+- Define branded schemas for `SignalId`, `OrganizationId`, `ProjectId`, `ConversationId`, `ConversationMessageId`, and `TimestampMs`.
+- Define `SignalScope`, `SignalSourceMessage`, `ProblemStatement`, `ProcessedByAgent`, `SignalInput`, and `Signal` with `Schema.Struct` / discriminated unions.
+- Add `SignalValidationError` with `Schema.TaggedErrorClass`.
+- Add `composeSignal = Effect.fn("Signal.compose")` that decodes input, rejects duplicate/out-of-order sources, preserves raw whitespace exactly, and returns a validated Signal.
+- Export the module from the root and an explicit `./signal` package subpath.
+- Add a package `test` script using cataloged Vitest.
+
+**Tests:**
+
+- Accept organization and project scopes.
+- Reject empty IDs, empty source list, empty problem-statement title/summary/desired outcome, empty constraint items, negative/fractional timestamps, duplicate source IDs, mixed conversations, and out-of-order timestamps.
+- Prove raw leading/trailing whitespace and source ordering survive unchanged.
+- Prove candidate/work-unit/run fields are absent from the decoded result.
+
+**Verification:**
+
+```bash
+bun run --cwd packages/primitives test
+bun run --cwd packages/primitives check-types
+bunx ultracite check packages/primitives/src/signal.ts packages/primitives/src/signal.test.ts packages/primitives/src/index.ts
+```
+
+---
+
+### Task 3: Establish minimal organization tenancy
+
+**Objective:** Give every durable Signal and global conversation a real tenant boundary instead of reusing a user ID or `main`.
+
+**Files:**
+
+- Modify: `packages/backend/convex/schema.ts`
+- Modify: `packages/backend/convex/authz.ts`
+- Create: `packages/backend/convex/organizations.ts`
+- Create: `packages/backend/convex/organizations.test.ts`
+
+**Implementation:**
+
+- Add `organizations` and `organizationMembers` tables.
+- Add `ensurePersonalOrganization`, idempotently creating one personal organization and owner membership for the authenticated user.
+- Add `getCurrent` and `requireOrganizationMember` helpers.
+- Keep full organization invitations, multiple active organizations, roles beyond owner/member, and organization settings out of scope.
+- Ensure every query/mutation denies access without both authenticated identity and membership.
+
+**Tests:**
+
+- First ensure creates one organization and owner membership.
+- Repeated ensure returns the same organization.
+- A second identity cannot read or mutate the first identity's organization.
+
+**Verification:**
+
+```bash
+bun run --cwd packages/backend test -- organizations
+bun run --cwd packages/backend check-types
+```
+
+---
+
+### Task 4: Rename execution signals to project events
+
+**Objective:** Remove the naming collision before creating the product `signals` table.
+
+**Files:**
+
+- Modify: `packages/backend/convex/schema.ts`
+- Modify: `packages/backend/convex/projects.ts`
+- Modify: `packages/backend/convex/projectIssues.ts`
+- Modify: `packages/backend/convex/agentWorkspace.ts`
+- Modify: `packages/backend/convex/artifactModel.ts`
+- Modify: `packages/backend/convex/README.md`
+- Optional migration file only if existing rows are present: `packages/backend/convex/migrations.ts`
+
+**Steps:**
+
+1. Inspect the active Convex deployment count for `projectSignals` before changing schema.
+2. If empty, cleanly rename the table and call sites to `projectEvents`.
+3. If non-empty, add a one-off internal migration that copies rows with preserved relations/timestamps, verify source/destination counts, then remove the old schema/table references. Do not leave a compatibility alias.
+4. Update `signals.md` seed copy to say “project events,” not product Signals.
+
+**Acceptance:**
+
+- `projectSignals` no longer exists in source or schema.
+- Existing project event behavior remains unchanged.
+- Product `signals` can be introduced without semantic ambiguity.
+
+**Verification:**
+
+```bash
+bun run --cwd packages/backend check-types
+```
+
+Exercise project connect, issue create/start, artifact update, and agent status once and confirm `projectEvents` receives the same events.
+
+---
+
+### Task 5: Normalize authenticated global user messages
+
+**Objective:** Persist exact tenant-scoped user evidence at the conversation ingress before the agent can create Signals.
+
+**Files:**
+
+- Modify: `packages/backend/convex/schema.ts`
+- Create: `packages/backend/convex/conversationMessages.ts`
+- Create: `packages/backend/convex/conversationMessages.test.ts`
+- Modify: `packages/agents/src/agents/zopu.ts`
+- Create: `packages/agents/src/auth.ts`
+- Modify: `packages/agents/package.json`
+- Modify: `apps/web/src/root.tsx`
+- Modify: `apps/web/src/lib/chat/constants.ts`
+- Modify: `apps/web/src/hooks/chat/use-chat-agent.ts`
+- Modify: `packages/auth/src/web/index.ts` only if the access-token helper is not already exported
+
+**Ingress sequence:**
+
+1. Web obtains the Better Auth/Convex access token with the installed `fetchAccessToken` API.
+2. The custom Flue fetch adds `Authorization: Bearer <token>` and a stable `x-zopu-request-id` to agent POSTs.
+3. Zopu route middleware requires the bearer token, sets it on a short-lived `ConvexHttpClient`, resolves current organization membership, and rejects an agent instance ID that is not that organization ID.
+4. Before `next()`, middleware clones and validates the direct payload and calls `conversationMessages.beginUserMessage` with exact text and request ID.
+5. After Flue returns its admission receipt, middleware patches `submissionId` and status `admitted`; on failure it marks the message `failed` and rethrows/returns the original failure.
+6. The web global agent ID becomes the current organization ID rather than `main`.
+
+**Important constraints:**
+
+- Do not trust organization ID, raw text, timestamp, or source role from an agent tool.
+- Do not parse `flueConversationBatches.recordsJson` for product commands.
+- Do not persist auth tokens.
+- Keep failed admissions as evidence with explicit status; do not silently delete them.
+- Ensure GET/SSE observation routes use the same organization authorization.
+
+**Tests:**
+
+- Unauthorized Flue route is rejected.
+- Organization A cannot use or observe organization B's agent ID.
+- Duplicate request ID is idempotent.
+- Exact whitespace/casing is stored.
+- Success records submission ID; failure records failed status.
+
+**Verification:**
+
+- Send one message containing leading/trailing whitespace through the running web app.
+- Confirm the agent replies.
+- Query Convex and confirm the normalized user message has exact raw text, organization scope, conversation/message identity, request ID, and admitted submission ID.
+- Sign in as another identity and confirm it cannot observe the first conversation.
+
+---
+
+### Task 6: Persist Signals atomically in Convex
+
+**Objective:** Resolve selected message IDs server-side, run the Effect constructor, and atomically insert one idempotent Signal plus ordered source snapshots.
+
+**Files:**
+
+- Modify: `packages/backend/convex/schema.ts`
+- Create: `packages/backend/convex/signals.ts`
+- Create: `packages/backend/convex/signals.test.ts`
+- Modify: `packages/backend/package.json`
+
+**Interface:**
+
+```ts
+createFromMessages({
+  organizationId,
+  projectId?,
+  conversationId,
+  messageIds,
+  problemStatement: { title, summary, desiredOutcome, constraints },
+  processedBy: { agentName, agentInstanceId },
+}) -> signalId
+```
+
+**Implementation:**
+
+- Expose an agent-token-gated mutation for Zopu and authenticated read queries for product clients.
+- Resolve every message from `conversationMessages` under the same organization and conversation.
+- Require role `user`, status `admitted`, non-empty ordered selection, and optional project ownership by the same organization.
+- Copy raw text/timestamps/submission IDs into `signalSources`; never accept snapshots from the agent.
+- Build `sourceKey` deterministically from organization, conversation, and ordered message IDs.
+- Run `composeSignal` from `@code/primitives/signal` before writes.
+- In one Convex mutation, return an existing row for the same source key or insert `signals` and all `signalSources` in ordinal order.
+- Add bounded `list` and `get` queries that enforce membership and return the composed source records.
+
+**Tests:**
+
+- Creates one global Signal from one user message.
+- Composes several ordered user messages into one Signal.
+- Preserves exact raw snapshots while storing a separate structured problem statement.
+- Rejects cross-organization, cross-conversation, assistant, failed, missing, duplicated, and unauthorized project messages.
+- Repeating the same source set returns the existing Signal without duplicate source rows.
+
+**Verification:**
+
+```bash
+bun run --cwd packages/backend test -- signals
+bun run --cwd packages/backend check-types
+bunx ultracite check packages/backend/convex/schema.ts packages/backend/convex/signals.ts packages/backend/convex/signals.test.ts
+```
+
+---
+
+### Task 7: Let Zopu decide and create Signals
+
+**Objective:** Give the global agent a narrow, validated mechanism to inspect eligible user evidence and create a Signal when the problem statement is coherent.
+
+**Files:**
+
+- Create: `packages/agents/src/tools/signals.ts`
+- Modify: `packages/agents/src/agents/zopu.ts`
+- Modify: `packages/agents/package.json`
+- Create: `packages/agents/scripts/signal-smoke.ts`
+
+**Tools:**
+
+1. `list_signal_source_messages`
+   - No free tenant input; organization comes from the authenticated agent instance ID.
+   - Returns a bounded list of admitted user messages not already used by a Signal, including message ID, exact text, and timestamp.
+2. `create_signal`
+   - Input: ordered message IDs, structured problem statement (`title`, `summary`, `desiredOutcome`, `constraints`), optional project ID.
+   - Calls the Convex `createFromMessages` mutation with `agentName: "zopu"` and the current organization-scoped instance ID.
+   - Returns only the Signal ID and source count.
+
+**Agent instruction:**
+
+- Continue normal planning conversation until the user's instructions form a coherent problem statement.
+- Do not create a Signal for greetings, exploration without a concrete problem, or every individual message.
+- When ready, call `list_signal_source_messages`, select only the messages composing the problem, then call `create_signal` once.
+- Tell the user the captured problem-statement title, summary, desired outcome, and constraints.
+- Do not create Candidate Work or start AgentOS in this slice.
+
+**Retry safety:**
+
+- Flue may replay tool calls after interruption. Convex source-key idempotency is authoritative.
+- The tool must surface domain errors; it must not swallow or convert them into fake success.
+
+**Verification:**
+
+Run the focused smoke script and a live browser scenario:
+
+1. Send three messages: an initial problem, a clarification, and an explicit final constraint.
+2. Observe Zopu create exactly one Signal after the statement is coherent.
+3. Confirm the Signal contains all selected raw messages in order and one structured problem statement with title, summary, desired outcome, and constraints.
+4. Restart the agent service/retry the final turn and confirm no duplicate Signal is inserted.
+5. Confirm no AgentOS actor, candidate, work unit, issue, or run is created.
+
+```bash
+bun run --cwd packages/agents signal:smoke
+bun run --cwd packages/agents check-types
+bun run --cwd apps/web check-types
+bunx ultracite check packages/agents/src/tools/signals.ts packages/agents/src/agents/zopu.ts packages/agents/scripts/signal-smoke.ts apps/web/src/root.tsx apps/web/src/lib/chat/constants.ts apps/web/src/hooks/chat/use-chat-agent.ts
+```
+
+---
+
+### Task 8: Final verification and cleanup
+
+**Objective:** Prove the complete Signal slice works and remove temporary migration/scaffolding.
+
+**Steps:**
+
+1. Run all focused tests and smoke scenarios from Tasks 2–7.
+2. Run Ultracite fix if necessary, then check every changed source/script/agent file.
+3. Run affected package type checks: primitives, backend, agents, auth if touched, and web.
+4. Run root `bun run check` and report unrelated pre-existing failures separately.
+5. Remove a one-off `projectSignals` migration only after row-count verification and successful cutover, unless the repository convention keeps completed migrations.
+6. Update existing backend/agent documentation only where names or commands became stale; do not add speculative docs.
+
+**Final acceptance criteria:**
+
+- Global conversations are organization-scoped and authenticated; `zopu/main` is gone.
+- Exact user text is stored before/with Flue admission and cannot cross organizations.
+- Zopu can intentionally compose one or more user messages into exactly one durable Signal.
+- Signal raw evidence and the structured processed problem statement are separate and queryable.
+- Source provenance is immutable and ordered.
+- Retry produces no duplicate Signal.
+- Existing project execution events still work under `projectEvents`.
+- Signal creation does not create Candidate Work, Work Unit, run, or AgentOS resources.
+- Effect v4 and AgentOS dependency versions come from workspace catalogs.
+- Focused tests, package type checks, runtime smoke, and root check are reported with evidence.
+
+## Risks and deliberate tradeoffs
+
+- **Minimal organization bootstrap:** This adds only the tenancy needed for Signals. Multi-org switching, invites, billing, and policy are separate components.
+- **Normalized user evidence plus Flue transcript:** There are temporarily two durable representations. Flue remains the canonical conversational transcript; `conversationMessages` is the application-domain evidence index required for authorization and provenance. Idempotent request IDs and submission links keep them correlated.
+- **No automatic Signal for every message:** This follows the product thesis and avoids task noise. The agent explicitly decides when the instructions are coherent.
+- **No separate Flow agent yet:** Zopu performs the first extraction using narrow tools. A future Flow Agent can adopt the same Convex command without changing the Signal primitive.
+- **No AgentOS here:** AgentOS begins only after future Candidate/Work Unit readiness and scheduling.
+- **No Signal status model yet:** Candidate attachment, knowledge capture, dismissal, and work promotion belong to later components. Adding them now would pre-design unimplemented workflows.
--- a/docs/DESIGN.md
+++ b/docs/DESIGN.md
--- a/docs/PRODUCT.md
+++ b/docs/PRODUCT.md
@@ -0,0 +1,897 @@
+# Zopo Work OS — Product
+
+> Status: working product specification  
+> Audience: product, design, operations, research, and agent teams  
+> Scope: product concepts, product boundaries, product behavior, and user value  
+> Excludes: implementation details, infrastructure, concrete technology choices, and low-level UI specifications
+
+## 1. Product summary
+
+Zopo Work OS is a persistent operating system for technical founders, product engineers, and small software teams who must manage the entire lifecycle of building and growing software across multiple products, companies, repositories, customers, and business functions.
+
+It replaces fragmented chat sessions, disconnected task trackers, scattered documents, and manually coordinated AI agents with one coherent system organized around **units of work**.
+
+The user interacts with one continuous workspace. From that workspace, the system discovers work, builds understanding, coordinates execution, requests human judgment when needed, tracks outcomes, and retains the resulting knowledge.
+
+The product is not a better chat application and not merely another project manager. It is a system that continuously converts company signals into structured, persistent, executable work.
+
+The core promise is:
+
+> One workspace that understands the company, turns signals into work, progresses that work autonomously, and brings the human in only when direction, judgment, permission, or taste is required.
+
+---
+
+## 2. Initial customer profile
+
+The initial ideal customer is a technical founder or small technical team that:
+
+- Operates one or more software products.
+- Works across several companies, client organizations, or repositories.
+- Moves constantly between engineering, product, customer support, sales, marketing, operations, and strategy.
+- Uses many tools but lacks a single model of what the company is trying to accomplish.
+- Already uses AI coding tools but finds their session- and thread-based workflows fragmented.
+- Needs more execution capacity without hiring a full department for every function.
+- Has a strong need for context continuity, reliable delegation, and visibility into autonomous work.
+
+Secondary early users may include:
+
+- Product engineers managing several initiatives.
+- Fractional CTOs.
+- Technical agencies and studios.
+- Solo software entrepreneurs.
+- Small product and engineering teams.
+- Operators responsible for multiple internal products or client environments.
+
+The initial product is technical-first because code is a clear execution domain with measurable artifacts, established workflows, and strong user familiarity. The broader product direction includes research, content, marketing, support, product operations, sales enablement, and other forms of knowledge and creative work.
+
+---
+
+## 3. Problem statement
+
+Modern technical work is fragmented in three ways.
+
+### 3.1 Work is fragmented across tools
+
+A single problem may begin in customer support, appear again in analytics, become an issue in a tracker, require research in a browser, turn into code in a repository, produce a pull request, and later require release notes and customer communication.
+
+Each tool stores a partial view. No tool owns the full lifecycle.
+
+### 3.2 AI work is fragmented across sessions
+
+Most AI products organize work around chats, threads, or isolated runs. The user must repeatedly decide:
+
+- Which conversation to open.
+- What context to restate.
+- Which model or agent to use.
+- Where the result should be stored.
+- How the output relates to existing work.
+- What changed after the work shipped.
+
+The conversation becomes the product structure even though conversations are temporary and work is persistent.
+
+### 3.3 Founders become the coordination layer
+
+In small teams, the founder acts as the bridge between every system and function. They remember decisions, connect customer feedback to product work, check whether tasks are blocked, move work between tools, review AI outputs, and decide what happens next.
+
+The founder becomes the human integration bus for the company.
+
+Zopo Work OS removes this coordination burden by maintaining a persistent model of work, context, state, evidence, execution, and outcomes.
+
+---
+
+## 4. Product thesis
+
+### 4.1 The conversation is not the product structure
+
+Conversation is the interface through which the user thinks, directs, reviews, and makes decisions.
+
+The durable structure is the **work unit**.
+
+A user should not have to create a new chat because they changed tasks. They should be able to move the scope of one persistent conversation between the whole workspace and a specific work unit.
+
+### 4.2 Work should be represented as outcomes, not activity
+
+The system should represent meaningful outcomes such as:
+
+- Fix Safari OAuth callback failures.
+- Reduce onboarding abandonment.
+- Launch team invitations.
+- Resolve an enterprise billing escalation.
+- Rewrite the pricing page.
+- Validate a new product direction.
+
+It should not promote every message, tool call, or agent action into a top-level task.
+
+### 4.3 The product should participate in the work
+
+Traditional project-management products store and display work. Zopo should also help discover, understand, plan, execute, verify, publish, and measure it.
+
+### 4.4 Autonomy should reduce attention, not increase noise
+
+The product should optimize for useful progress with minimal required human attention.
+
+Autonomy is successful when the system makes correct progress, keeps the user informed at the right level, and asks for intervention only when it is necessary.
+
+### 4.5 Knowledge should compound
+
+Every decision, result, failed approach, customer signal, and artifact should improve the system’s understanding of the organization and make future work faster and more accurate.
+
+---
+
+## 5. Core product objects
+
+The product should use a small set of durable concepts. These concepts should remain stable even as the product expands into new domains.
+
+## 5.1 Organization
+
+An organization is a hard business, permission, and knowledge boundary.
+
+An organization may represent:
+
+- A company.
+- A client.
+- A startup.
+- An internal business unit.
+- A personal software portfolio.
+
+An organization owns its users, products, policies, integrations, knowledge, work, and history.
+
+Information must never move between organizations implicitly.
+
+## 5.2 Product or project
+
+A product or project is a durable operating context within an organization.
+
+It may represent:
+
+- A software product.
+- A repository-backed application.
+- A client engagement.
+- An internal platform.
+- A website or service.
+- A focused initiative with its own ongoing context.
+
+A project contains its goals, product knowledge, working conventions, connected sources, relevant people, and active work.
+
+Projects should reduce context ambiguity without forcing the user to manually maintain complex folder structures.
+
+## 5.3 Goal
+
+A goal states what the organization or project is trying to achieve.
+
+Examples:
+
+- Reduce onboarding failure.
+- Reach a reliability target.
+- Launch enterprise support.
+- Improve trial-to-paid conversion.
+- Close the first ten enterprise customers.
+
+Goals help the system distinguish valuable work from merely possible work.
+
+A work unit may support one or more goals, but every important work unit should have a clear reason for existing.
+
+## 5.4 Signal
+
+A signal is raw information that may matter.
+
+Examples:
+
+- A support ticket.
+- A customer comment.
+- An error spike.
+- A deployment failure.
+- A sales objection.
+- A message in a team channel.
+- An analytics change.
+- A founder’s thought in the global conversation.
+
+A signal is not automatically a task.
+
+Signals can be:
+
+- Attached to existing work.
+- Converted into candidate work.
+- Saved as knowledge.
+- Dismissed.
+- Marked as irrelevant or duplicated.
+
+## 5.5 Candidate work
+
+Candidate work is a proposed work unit that has not yet been accepted as durable active work.
+
+The system creates candidates when it believes a signal or cluster of signals deserves action.
+
+A candidate should explain:
+
+- What outcome is proposed.
+- Why it matters.
+- Which evidence supports it.
+- Which project and goal it belongs to.
+- How confident the system is.
+- Whether similar work already exists.
+
+The user can accept, edit, merge, defer, or dismiss it.
+
+## 5.6 Work unit
+
+A work unit is the central object of the product.
+
+It is a persistent, stateful representation of one meaningful outcome.
+
+A work unit owns:
+
+- Objective.
+- Desired result.
+- Scope and non-goals.
+- Current understanding.
+- Requirements.
+- Success criteria.
+- Status.
+- Priority.
+- Dependencies.
+- Blockers.
+- Decisions.
+- Evidence.
+- Plan.
+- Human actions.
+- Agent activity.
+- Artifacts.
+- Results.
+- Learning.
+
+The work unit persists across multiple conversations, agent runs, people, tools, and time periods.
+
+A work unit is not identical to:
+
+- A single prompt.
+- A chat thread.
+- A single agent session.
+- A pull request.
+- A checklist item.
+- A repository branch.
+
+Those may all exist inside or underneath a work unit.
+
+## 5.7 Step
+
+A step is a bounded action within a work unit.
+
+Examples:
+
+- Inspect relevant logs.
+- Reproduce the failure.
+- Draft an implementation plan.
+- Add tests.
+- Review a preview.
+- Contact affected customers.
+
+Steps help organize execution, but they should not become another noisy task-management layer. They are visible when useful and hidden when the user only needs the higher-level outcome.
+
+## 5.8 Run
+
+A run is one attempt by an agent or workflow to progress a work unit.
+
+Examples:
+
+- Research the root cause.
+- Implement a change.
+- Review a proposed solution.
+- Run verification.
+- Prepare release material.
+
+A work unit can have several runs, including parallel or repeated attempts.
+
+Runs are subordinate to the work unit and should not replace it as the primary product object.
+
+## 5.9 Artifact
+
+An artifact is a durable output or piece of evidence produced or collected during work.
+
+Examples:
+
+- Pull request.
+- Commit.
+- Patch.
+- Design.
+- Specification.
+- Test report.
+- Screenshot.
+- Preview.
+- Research memo.
+- Customer response draft.
+- Launch plan.
+
+Artifacts should be attached to the work unit and accessible from its history and current state.
+
+## 5.10 Decision
+
+A decision records an important human or system choice and the reasoning behind it.
+
+Examples:
+
+- Approve a proposed plan.
+- Choose one design direction.
+- Reject a migration strategy.
+- Delay a feature.
+- Accept a known limitation.
+
+Decisions should remain visible after the immediate conversation is over so future agents do not repeat settled debates.
+
+## 5.11 Approval
+
+An approval is a specific human permission required before a sensitive or consequential action.
+
+Examples:
+
+- Merge code.
+- Deploy to production.
+- Send a customer message.
+- Access sensitive data.
+- Spend money.
+- Change business policy.
+
+Approvals should be precise, inspectable, and bounded. The user should know exactly what will happen after approval.
+
+## 5.12 Result and learning
+
+A result records what happened after work was completed or published.
+
+It should compare:
+
+- Intended outcome.
+- Expected impact.
+- Actual outcome.
+- Measurement period.
+- Unexpected effects.
+- Recommended follow-up.
+
+Learning is the reusable knowledge extracted from the work. It should improve future planning and execution across the relevant organization or project.
+
+---
+
+## 6. Work lifecycle
+
+Work moves through four broad phases. These phases should remain conceptually consistent across engineering, product, marketing, support, and other domains.
+
+## 6.1 Discover
+
+The system observes conversations and connected information sources to identify problems, opportunities, questions, risks, and requests.
+
+Discovery includes:
+
+- Extracting signals.
+- Grouping related signals.
+- Identifying duplicates.
+- Connecting signals to existing work.
+- Proposing candidate work.
+- Relating work to goals and projects.
+
+The goal of discovery is not to create the largest possible backlog. It is to identify meaningful work with sufficient evidence and relevance.
+
+## 6.2 Understand
+
+The system gathers context and develops a shared model of the problem.
+
+Understanding may include:
+
+- Research.
+- Code or system inspection.
+- Customer evidence.
+- Analytics.
+- Existing decisions.
+- Constraints.
+- Open questions.
+- Risks.
+- Success criteria.
+
+The result should be an actionable understanding, not an endless research report.
+
+## 6.3 Create and iterate
+
+The system coordinates the production of a solution.
+
+Depending on the work, this can include:
+
+- Code.
+- Product specifications.
+- Designs.
+- Documentation.
+- Tests.
+- Customer communication.
+- Launch assets.
+- Research outputs.
+- Business recommendations.
+
+The system should produce intermediate artifacts, verify progress, and incorporate human feedback without losing the work unit’s continuity.
+
+## 6.4 Publish and learn
+
+The solution is released, delivered, shared, or otherwise put into use.
+
+The system then follows the outcome through:
+
+- Deployment status.
+- Error rates.
+- Adoption.
+- Customer reactions.
+- Conversion.
+- Support volume.
+- Revenue impact.
+- Qualitative feedback.
+
+The lifecycle ends only when the work has either produced a result, been intentionally stopped, or been superseded by another decision.
+
+---
+
+## 7. Work-unit boundaries
+
+The quality of the system depends heavily on how it divides work.
+
+## 7.1 A work unit should represent one independently meaningful outcome
+
+A good work unit can be summarized in one clear sentence and can reach a recognizable result.
+
+Good examples:
+
+- Fix Safari OAuth callback failures.
+- Decide whether to support SAML this quarter.
+- Reduce time-to-first-value during onboarding.
+- Prepare and launch the team invitations feature.
+
+Poor examples:
+
+- Improve the product.
+- Marketing.
+- Work on onboarding.
+- Open the repository.
+- Read the logs.
+
+The first group is too broad. The second group is too granular.
+
+## 7.2 Split work when
+
+A work unit should be split when:
+
+- It contains multiple independent outcomes.
+- Different parts have different owners or approval paths.
+- The parts belong to different organizations or permission boundaries.
+- They have different deadlines or success criteria.
+- One part can finish while another remains active.
+- The work has become difficult to summarize or review.
+- A child outcome deserves its own lifecycle and result.
+
+## 7.3 Merge work when
+
+Work should be merged when:
+
+- Two candidates describe the same underlying outcome.
+- Different channels produced duplicate reports of the same problem.
+- One candidate is merely evidence for an existing unit.
+- Neither item can be meaningfully completed independently.
+
+The system may propose a merge, but uncertain merges should remain reversible and user-reviewable.
+
+## 7.4 Parent and child work
+
+Large initiatives may contain child work units.
+
+A parent should represent a larger result, while each child still has an independently meaningful outcome.
+
+Example:
+
+**Parent initiative:** Restore OAuth reliability
+
+- Fix Safari callback failures.
+- Improve OAuth setup diagnostics.
+- Update documentation.
+- Notify affected customers.
+- Monitor setup completion after release.
+
+Parent units should summarize progress and dependencies without replacing the detail of their children.
+
+---
+
+## 8. Conversation model
+
+The product uses one persistent conversational surface with two scopes.
+
+## 8.1 Global conversation
+
+Global conversation is used to think and act across the workspace.
+
+The user can:
+
+- Introduce new ideas or problems.
+- Ask what needs attention.
+- Compare work across projects.
+- Reprioritize.
+- Create or modify work.
+- Ask for summaries.
+- Discuss dependencies.
+- Request new research or execution.
+
+The system should automatically connect global messages to relevant projects and work units while preserving the original source.
+
+## 8.2 Contextual conversation
+
+Contextual conversation focuses the same composer and interaction model on one work unit.
+
+The user can:
+
+- Add requirements.
+- Answer questions.
+- Review progress.
+- Change direction.
+- Approve a plan.
+- Request another attempt.
+- Ask for explanation.
+- Continue work from an artifact.
+
+Entering contextual conversation should not create a new thread. It changes the active scope of the persistent workspace.
+
+## 8.3 Conversation boundaries
+
+Conversation should not be the source of truth for work state.
+
+Important facts, decisions, requirements, approvals, artifacts, and results should be extracted into structured product objects while preserving links to their source conversation.
+
+---
+
+## 9. Autonomous behavior
+
+The product should continuously observe, understand, organize, execute, escalate, and learn.
+
+## 9.1 The system may autonomously
+
+- Attach new evidence to existing work.
+- Update summaries and understanding.
+- Detect stale or blocked work.
+- Propose new work.
+- Run safe research.
+- Prepare plans and drafts.
+- Produce code or other artifacts inside approved boundaries.
+- Run verification.
+- Suggest priorities.
+- Monitor completed work.
+- Create follow-up candidates.
+- Summarize activity for the user.
+
+## 9.2 The system should request human involvement for
+
+- Strategic direction.
+- Ambiguous product decisions.
+- Business tradeoffs.
+- Sensitive permissions.
+- High-risk actions.
+- External communication.
+- Production changes.
+- Priority conflicts.
+- Conflicting evidence.
+- Actions outside previously granted policy.
+
+## 9.3 The system should not
+
+- Create large amounts of speculative work without evidence.
+- Treat confidence as certainty.
+- Hide failures or uncertainty.
+- Silently cross organization boundaries.
+- Reopen settled decisions without new evidence.
+- Perform irreversible actions without appropriate authority.
+- Optimize for activity instead of outcomes.
+
+---
+
+## 10. Human-in-the-loop model
+
+The user should not have to inspect every work unit to find what requires attention.
+
+The product should centralize human requests into an **Attention Queue**.
+
+Each request should explain:
+
+- What is required.
+- Why it is required.
+- What the system recommends.
+- What evidence supports the recommendation.
+- What will happen after approval.
+- What happens if the user does nothing.
+- How urgent the request is.
+- Whether the action is reversible.
+
+Human requests fall into several categories:
+
+- Decision.
+- Approval.
+- Clarification.
+- Access request.
+- Review.
+- Blocker resolution.
+- Risk alert.
+
+The product should minimize unnecessary approvals by supporting explicit standing policies, while preserving clear control over sensitive actions.
+
+---
+
+## 11. Provenance and trust
+
+The user must be able to understand why the system believes something and what caused an action.
+
+Every important claim should carry provenance.
+
+Provenance may include:
+
+- Source message.
+- Customer ticket.
+- Repository change.
+- Error report.
+- Analytics event.
+- Document.
+- Agent observation.
+- Human decision.
+
+Claims should be distinguishable as:
+
+- Verified.
+- Reported.
+- Inferred.
+- Assumed.
+- Conflicting.
+- Outdated.
+
+The primary interface should remain readable, but deeper evidence and derivation should be available on demand.
+
+The system should never present an agent-generated summary as equivalent to primary evidence.
+
+---
+
+## 12. Knowledge model
+
+Zopo should accumulate several kinds of organizational knowledge.
+
+### 12.1 Canonical knowledge
+
+Durable, reviewed descriptions of:
+
+- Business.
+- Product.
+- Customers.
+- Design principles.
+- Architecture concepts.
+- Working conventions.
+- Policies.
+- Goals.
+
+### 12.2 Operational knowledge
+
+Current structured state:
+
+- Active work.
+- Priorities.
+- Dependencies.
+- Ownership.
+- Blockers.
+- Approvals.
+- Results.
+
+### 12.3 Episodic knowledge
+
+What happened over time:
+
+- Conversations.
+- Runs.
+- Errors.
+- Decisions.
+- Reviews.
+- Releases.
+- Customer reactions.
+
+### 12.4 Learned patterns
+
+Reusable conclusions such as:
+
+- Common causes of failure.
+- Customer preferences.
+- Repeated objections.
+- Effective launch patterns.
+- Known limitations.
+- Preferred technical and product approaches.
+
+Knowledge should always retain its scope. Personal preferences, project-specific facts, and organization-wide truths should not be mixed blindly.
+
+---
+
+## 13. Product boundaries
+
+## 13.1 Zopo is the control layer, not the replacement for every specialist tool
+
+Specialist systems may continue to own their native records and actions.
+
+Examples include:
+
+- Source control.
+- Customer support.
+- Team communication.
+- Analytics.
+- Billing.
+- Deployment.
+- Documents.
+
+Zopo should provide the unified model of what matters, what state it is in, what should happen next, and whether the outcome worked.
+
+## 13.2 Zopo should own the work graph
+
+The work graph connects:
+
+- Organizations.
+- Projects.
+- Goals.
+- Signals.
+- Work units.
+- Dependencies.
+- Decisions.
+- Runs.
+- Artifacts.
+- Results.
+- Learnings.
+
+This graph is the product’s durable source of coordination and context.
+
+## 13.3 Execution systems are replaceable
+
+The product should present execution as a capability beneath the work unit. Users should not have to care which internal agent, model, or harness performed a run unless inspection is useful.
+
+## 13.4 The product should not expose unnecessary AI configuration
+
+Users should not normally need to choose:
+
+- Model.
+- Thinking level.
+- Agent framework.
+- Context-window strategy.
+- Execution runtime.
+- Tool routing.
+
+The system should choose automatically based on task, risk, cost, and policy.
+
+---
+
+## 14. Product optimization
+
+The product should optimize for:
+
+> Maximum useful progress with minimum required human attention.
+
+Key product measures include:
+
+- Correct extraction of meaningful work.
+- Low false-positive candidate creation.
+- Time from signal to structured understanding.
+- Time to first useful action.
+- Accepted work units reaching meaningful outcomes.
+- Reduction in repeated context gathering.
+- Human attention required per completed outcome.
+- Quality of decisions and outputs.
+- Trust, inspectability, and reversibility.
+- Reuse of accumulated knowledge.
+- Improvement in future work from past results.
+
+The product should not primarily optimize for:
+
+- Number of chats.
+- Time spent in the interface.
+- Number of tasks created.
+- Number of agent runs.
+- Number of notifications.
+- Raw model usage.
+
+A successful day may involve the user opening the product briefly, resolving a few high-value decisions, and seeing that many other units progressed correctly without them.
+
+---
+
+## 15. Business value delivered through the product
+
+Zopo provides four forms of value.
+
+### 15.1 Execution capacity
+
+A small team can progress more work without proportionally increasing headcount.
+
+### 15.2 Coordination reduction
+
+The product handles the repetitive work of gathering context, updating state, linking related information, following up, and preparing outputs.
+
+### 15.3 Continuity
+
+Work keeps its context, history, decisions, and artifacts across tools and time.
+
+### 15.4 Better opportunity capture
+
+The system notices recurring problems, customer opportunities, operational risks, and important relationships that the team may otherwise miss.
+
+---
+
+## 16. Initial product scope
+
+The first strong product loop should be:
+
+1. The user starts or connects a software project.
+2. The product establishes project context.
+3. The user describes desired work through the global composer.
+4. The system creates or updates a work unit.
+5. The work unit is clarified and accepted.
+6. The system progresses the work autonomously.
+7. The user reviews only necessary decisions and outputs.
+8. The system produces verified artifacts.
+9. The user approves publication or integration where required.
+10. The product updates the work unit and retains the resulting knowledge.
+
+The first version should prove that persistent work units are a better product structure than disposable agent chats.
+
+---
+
+## 17. Long-term product direction
+
+The technical product is the starting point, not the final boundary.
+
+The same work-unit model can later support:
+
+- Product research.
+- Marketing campaigns.
+- Content production.
+- Sales enablement.
+- Customer support operations.
+- Pricing work.
+- Business analysis.
+- Hiring.
+- Internal operations.
+
+The long-term vision is a general operating system for creative and knowledge work.
+
+The enduring principles are:
+
+- One persistent workspace.
+- Work units instead of chat sessions.
+- Outcome-oriented execution.
+- Invisible orchestration.
+- Explicit human authority.
+- Strong provenance.
+- Compounding organizational knowledge.
+
+---
+
+## 18. Non-goals for the initial product
+
+The initial product is not intended to be:
+
+- A full replacement for every external tool.
+- A general-purpose social collaboration platform.
+- A traditional kanban board with AI decoration.
+- A model playground.
+- A prompt-management product.
+- A marketplace of visible agents.
+- A system that creates work faster than users can evaluate it.
+- A fully autonomous company with no human authority.
+
+---
+
+## 19. Product principles
+
+1. **Organize around work, not conversations.**
+2. **Represent outcomes, not activity.**
+3. **Keep the system calm while the machinery remains powerful.**
+4. **Bring humans in for judgment, not clerical coordination.**
+5. **Expose evidence and uncertainty.**
+6. **Make important actions understandable and reversible.**
+7. **Preserve organization and project boundaries.**
+8. **Prefer one coherent model over many disconnected features.**
+9. **Let knowledge compound across completed work.**
+10. **Measure success by outcomes and reduced attention.**
+
+---
+
+## 20. Working product statement
+
+Zopo Work OS is an autonomous operating system for technical founders and small product teams. It observes work across the company, turns fragmented signals into persistent units of work, progresses those units using agents and tools, and brings the human in only when judgment, permission, or direction is required.
+
+It gives the user one continuous workspace for moving from idea or problem to verified, shipped, measurable outcome while preserving context and building a durable understanding of the company over time.
--- a/docs/TECH.md
+++ b/docs/TECH.md