PROJ is CyberOS's project tracker, sprint engine, and Engagement billing surface in one. The data model is Issue -> Cycle -> Project plus Engagement (the contract). Status is a closed enum (backlog / todo / in-progress / in-review / done / cancelled) with a configurable per-project workflow on top. Priority is the standard urgent / high / medium / low / none. Mutations are optimistic locally, server-canonical eventually; Yjs CRDTs let two Members edit the same description offline and merge without conflict. Every issue can link to memory entries - a memory becomes a citation, a decision-log row becomes a sub-task. AI features are first-class: CUO drafts the cycle review at end-of-cycle; the blocker-detector watches comments for "blocked by"; estimate calibration tracks estimated vs actual hours per Member per task class.

• Strategic role: orchestration spine - CRM -> PROJ -> TIME -> INV -> KB -> memory
• Status: planned - P1; slice 1 in build, P1 mid in the sequence
• Primitives: 4 - Issue, Cycle, Project, Engagement
• Cross-module joins: 7 - CRM, TIME, INV, KB, REW, memory, OKR
• Sync: optimistic - WebSocket + server-canonical
• Offline: Yjs CRDT - offline-edit + merge
• Memory integration: bidirectional - Issue <-> memory cite + Layer-3 ingest
• Engagement model: 3 modes - T&M, fixed-fee, retainer
• i18n: vi + en - status / UI strings / cycle reviews
• AI features: 5 - triage, blocker, review, calibration, scope-creep
• UI surfaces: 4 - Board, Timeline, Gantt, Brief
• Depends on: AUTH, memory, TIME, plus AI, MCP, OBS, NATS
• Est. LoC: ~11,000 - Rust + TS SPA + Yjs

The bigger picture - three strategic roles

PROJ is the orchestration spine of CyberOS - the module where every other module's data joins around a unit of work. Reading this page as "yet another Linear clone" misses the point: three distinct roles land in one Postgres schema, and the design treats them as equal-weight requirements.

Role 1 - orchestration spine

Every module's join lives here. CRM creates a deal -> PROJ converts it into an Engagement. TIME logs hours against an Issue, INV pulls those hours via the Engagement rate card. KB archives the cycle review. REW pulls Member calibration. OKR ties to Project status. Memory ingests every state change as a Layer-3 node. PROJ is where the threads of work cross - and where the audit trail of "did we do what we said we'd do" lands.

Role 2 - memory-anchored decisions

Issues cite memories, not stale prose. An Issue is a node that references a memory (the decision that spawned it, the spec it implements, the prior issue it supersedes). Every state change emits a chained audit row to the local memory. When the cycle closes, the review draft cites the actual decisions that drove the work - not "we decided to do X" without a source. This is the difference between a Jira ticket and a verifiable work record.

Role 3 - Engagement billing surface

Consultancies need this - product trackers assume it away. Linear assumes a product team. Jira assumes either. We assume consultancy delivery: a Client signs an Engagement at a billing mode (T&M / fixed-fee / retainer) with a localised rate card, time entries are billable-by-default with per-task overrides, and the TIME -> INV chain rides on the Engagement, not the Project. Pure product trackers cannot model this without bolting on a billing add-on; we model it natively.

The PROJ join surface (every module touches it)

flowchart LR
  CRM["CRM<br/>Deal won"]
  PROJ["PROJ<br/>Engagement / Project / Cycle / Issue"]
  TIME["TIME<br/>billable hours"]
  INV["INV<br/>billable line items"]
  KB["KB<br/>cycle review archive"]
  REW["REW<br/>calibration -> bonus"]
  OKR["OKR<br/>Project -> key result"]
  memory["memory<br/>Layer-3 ingest + audit chain"]
  PORTAL["PORTAL<br/>client-visible view"]
  EMAIL["EMAIL<br/>thread -> issue"]
  CRM -->|"deal.won -> engagement.create"| PROJ
  EMAIL -->|"client reply -> comment / issue"| PROJ
  PROJ -->|"issue tracked + rate card"| TIME
  TIME -->|"hours x rate (billable)"| INV
  PROJ -->|"cycle review, MD doc"| KB
  PROJ -->|"calibration snapshot"| REW
  PROJ -->|"project status"| OKR
  PROJ -->|"every mutation -> audit row"| memory
  PROJ -->|"client-visible Project view (P2)"| PORTAL
  memory -.->|"cite memory"| PROJ
  classDef hub fill:#e0e7ff,stroke:#3730a3,stroke-width:3px,color:#1e1b4b
  classDef other fill:#f5ede6,stroke:#45210e
  classDef memory fill:#fef6e0,stroke:#9c750a
  class PROJ hub
  class CRM,TIME,INV,KB,REW,OKR,PORTAL,EMAIL other
  class memory memory

Every arrow is a data dependency. Removing PROJ from the architecture means rebuilding the same join in 8 other places - that's why PROJ is the orchestration spine, not just "the issue tracker."

Auto vs manual operations matrix

Why PROJ exists

Linear's data-model insight was that three primitives - Issue, Cycle, Project - cover almost every workflow that product and services teams actually do, and that a fourth primitive ("Engagement") covers the consultancy case once you add a rate card and a billable / non-billable distinction. The UX insight was the sync-engine: the user never waits for a server round-trip; the server is the eventual authority, but the local copy is the one being typed into. PROJ replicates both insights and adds the CyberOS-specific bindings: every issue links to memories (so a decision-log row can spawn a sub-task), every comment is a candidate for a blocker-detection nudge, every cycle ends with a CUO-drafted review the Account Manager can edit before sending to the Client.

• Sync-engine feel. Optimistic local updates, WebSocket fan-out, server-canonical rebase on conflict. No spinners on the hot path; offline edits merge via Yjs CRDT.
• Engagement primitive. Where Linear has "Project", we have "Project under Engagement". Rate cards, billable rules, and the TIME -> INV flow ride on the Engagement.
• Memory-linked work. Every issue can cite a memory; tasks are ingested into Layer 3; cross-project pattern queries answer "what's the pattern in late tasks?".

The bet is that consultancies do not need a different tracker per client - they need one tracker that understands the consulting shape natively. Linear validated the three-primitive model; CyberOS extends it with the contract layer and the AI-native loop. The sync-engine is the rest of the way to "feels instant" - Linear documented the pattern; we re-implement it because the consulting cycle is two-weeks-anchored to a Client review, and that review needs to be CUO-draftable from the comment stream.

What it does - 5W1H2C5M

A structured decomposition of PROJ's scope.

Orchestration spine - cross-module join contracts

PROJ is downstream of 2 modules (CRM, EMAIL) and upstream of 6 (TIME, INV, KB, REW, OKR, PORTAL); every other CyberOS module that touches "work" reads from or writes to a PROJ join contract. The contracts are stable interfaces - modules can be re-implemented behind them without breaking PROJ. The table below is the canonical list; every change to PROJ's data model must consider whether it widens a contract or breaks one.

Contract stability policy

Each join contract above is a versioned interface. Breaking changes require:

• ADR with the counterparty module owner co-signing.
• Deprecation window: >= 1 minor release with both old + new shape supported and a deprecation warning on old.
• Migration test: an integration test that exercises both versions end-to-end.
• Memory: the deprecation itself becomes a decision memory at memories/decisions/proj-contract-change-<name>.md for traceability.

This is a deliberate brake: PROJ's data shape is the most expensive thing in CyberOS to mutate, because 8 downstream modules read from it.

Engagement economics - the consultancy-native primitive

The fourth primitive - Engagement - is where CyberOS earns its "consultancy-native" framing. A pure product tracker has Project but not the contract under which Project runs. A pure ERP has the contract but not the issues. PROJ owns both, joined by project.engagement_id. Below is the full economic model: billing modes, rate-card mechanics, and the per-Member, per-task-class billability rules that drive INV.

Three billing modes

Rate card structure (per Engagement)

Every Engagement has 1..N rate-card rows. A row is (role x currency) -> hourly rate + billable default. Currency is fixed per row to avoid FX drift mid-cycle.

engagement: acme-q3-platform-build
billing_mode: T_AND_M
currency_primary: VND
rate_cards:
  - role: architect
    rate_vnd_per_hour: 2,500,000
    rate_usd_per_hour: 100
    billable_default: true
  - role: senior_engineer
    rate_vnd_per_hour: 1,800,000
    rate_usd_per_hour: 72
    billable_default: true
  - role: mid_engineer
    rate_vnd_per_hour: 1,200,000
    rate_usd_per_hour: 48
    billable_default: true
  - role: junior_engineer
    rate_vnd_per_hour: 700,000
    rate_usd_per_hour: 28
    billable_default: false  # juniors non-billable on this engagement
non_billable_categories:
  - "internal_meeting"
  - "training"
  - "rework_due_to_our_fault"

Billable / non-billable computation

The default cascade for "is this hour billable?":

1. Member-level override on the TIME entry - if the Member set billable=false explicitly, that wins.
2. Task class - if the Issue is labelled in non_billable_categories on the Engagement (e.g. internal_meeting, rework_due_to_our_fault), it is non-billable.
3. Role default - fall back to rate_card.billable_default for the Member's role.
4. Otherwise the hour is billable.

The decision is logged as a snapshot in the TIME entry (immutable) so retroactive rate-card changes don't shift past invoices.

Margin watchdog (planned, P2)

For fixed-fee engagements, the scope-creep risk (R-PROJ-013) needs an early warning. PROJ surfaces a per-Engagement margin chart: (fee x % milestone done) - (hours_burned x cost_per_hour). When projected margin drops below 30% of the original budget, CUO Notify pings the AM + CEO. This is a one-screen view in the SPA, not a separate module - because the consultancy founder needs to see it without context switching.

Memory-anchored decisions - issues cite memories

In a typical tracker, an Issue's why lives in stale prose ("Discussed in 5/14 standup - see Confluence page X" - which has since moved). In PROJ, an Issue's why lives in memory as a memory the Issue cites. When memory changes - a decision is superseded, a fact is corrected - the Issue's citation graph updates. This is the difference between a project history that ages well and one that decays.

Three citation relations

The decision -> sub-task pattern

A common workflow: a decision memory becomes a parent Issue with sub-tasks. The skill that handles this is cuo.cpo.decision-to-issues@1:

sequenceDiagram
  autonumber
  participant U as User ("convert this decision to issues")
  participant CU as CUO/CPO skill
  participant BR as memory read
  participant PR as PROJ
  participant BW as memory write (audit)
  U->>CU: invoke decision-to-issues@1 (memory path)
  CU->>BR: fetch memories/decisions/{slug}.md
  BR-->>CU: decision text + sub-decisions
  CU->>CU: extract action items via LLM (structured output)
  CU->>U: present draft (parent issue + N sub-tasks)
  U->>CU: confirm / edit
  CU->>PR: create_issue (parent) + create_issue x N (children, implements relation)
  PR->>BW: emit proj.issue_create x (N+1) audit rows, each citing the decision memory
  BW-->>PR: ok
  PR-->>U: issues created, memory-linked

This pattern is how a strategic decision in memory becomes verifiable work in PROJ - with a citation graph that survives leadership changes and tracker migrations.

Audit chain across PROJ and memory

Every PROJ mutation writes two audit rows: one in PROJ's own history_event table (fast, queryable) and one in the local memory (chained, signed, exportable). The memory row carries the same chain hash that PROJ's row references via history_event.memory_chain. This dual-write is the mechanism behind the "decisions live in memory, not Jira" claim - PROJ's local history is useful for the UI, but the cryptographic provenance lives in memory.

-- PROJ history_event row (Postgres, fast queries)
INSERT INTO history_event (id, issue_id, actor_id, kind, from_value, to_value, ts, memory_chain)
VALUES (
  'he_01HZ...',
  'is_01HZ...',
  'sub_stephen@...',
  'status',
  'in-progress',
  'in-review',
  '2026-05-15T08:42:11Z',
  '69e6...488a'   -- <- references the memory audit row's chain hash
);

-- memory audit row (immutable, chained, exportable)
{
  "seq": 18420,
  "ts_ns": 1763112131_000_000_000,
  "op": "put",
  "path": "memories/projects/proj-3110-status-transition.md",
  "actor": "sub_stephen@cyberskill.world",
  "extra": { "issue_code": "PROJ-3110", "from": "in-progress", "to": "in-review" },
  "prev_chain": "...",
  "chain": "69e6...488a"
}

Liquid-Glass UI surfaces - Board / Timeline / Gantt / Brief

PROJ is the design-system exemplar for the rest of CyberOS - every other module's table, timeline, and brief view borrows from PROJ's four canonical UI surfaces. The Liquid-Glass surface treatment (Part 21 of the design system: Umber #45210E base, Ochre #F4BA17 accent, blur backdrop, generous whitespace, Be Vietnam Pro 16px base) lands here first because PROJ is what Members look at all day.

Design tokens (PROJ-specific overlay)

PROJ inherits all tokens from website/docs/assets/tokens.css and adds an indigo overlay because the status colour palette is most readable in cool tones (warm anchors would clash with priority colours).

/* tokens.proj.css - PROJ-specific overlay (loaded after tokens.css) */
:root {
  --proj-indigo: #4f46e5;     /* primary action */
  --proj-indigo-bg: #eef2ff;  /* surface tint */
  --proj-indigo-dk: #3730a3;  /* on-hover, text accent */

  /* Status colours - readable on both light + dark surfaces */
  --status-backlog: #94a3b8;   /* slate-400 */
  --status-todo: #3b82f6;      /* blue-500 */
  --status-inprog: #f59e0b;    /* amber-500 */
  --status-inreview: #8b5cf6;  /* violet-500 */
  --status-done: #10b981;      /* emerald-500 */
  --status-cancelled: #64748b; /* slate-500, dimmed */

  /* Priority colours */
  --priority-urgent: #dc2626;  /* red-600 */
  --priority-high: #f97316;    /* orange-500 */
  --priority-medium: #eab308;  /* yellow-500 */
  --priority-low: #22c55e;     /* green-500 */
  --priority-none: transparent;

  /* Liquid-Glass surface (PROJ's primary card treatment) */
  --proj-glass-bg: rgba(248, 250, 252, 0.72);
  --proj-glass-border: rgba(79, 70, 229, 0.12);
  --proj-glass-blur: blur(18px) saturate(180%);
}

Accessibility commitments

• WCAG 2.1 AA contrast ratios on every status/priority pill - measured in CI via axe-core on the Storybook build.
• Keyboard-only navigation for Board + Timeline + Brief - an explicit acceptance criterion in the SPA's e2e suite.
• Screen-reader labels on every status transition: "Status changed from In progress to In review" announced via aria-live=polite.
• Focus trap discipline: the Brief modal traps focus; Esc closes without losing the draft (Yjs preserves it).
• Reduce-motion mode: prefers-reduced-motion: reduce disables drag animations and Yjs presence cursors.
• Vietnamese diacritic-correct fonts: Be Vietnam Pro 400/600/800 weights; fallback stack "Be Vietnam Pro", "Inter", system-ui.

Architecture

PROJ is one axum binary with four surfaces (sync-engine WebSocket, REST admin, GraphQL federated subgraph, MCP tool catalogue) and three stores (Postgres for canonical state + Yjs document snapshots, Redis for WS rooms and search cache, S3 for attachments). NATS JetStream fans mutations out to every connected SPA.

graph TB
  subgraph CLIENT ["Clients"]
    SPA["SPA<br/>React + Zustand"]
    MOBILE["Mobile (P3)"]
    AGENT["CUO agent<br/>via MCP"]
  end
  subgraph EDGE ["Edge"]
    WSGW["WebSocket gateway<br/>JWT-authed"]
    GQL["GraphQL subgraph<br/>(federated)"]
    REST["Admin REST"]
    MCP["MCP tool surface"]
  end
  subgraph CORE ["PROJ service (Rust)"]
    SYNC["Sync engine<br/>optimistic + rebase"]
    CRDT["Yjs document server<br/>(ywasm)"]
    WF["Workflow engine<br/>status transitions"]
    AI["AI hooks<br/>blocker / review / calibration"]
    MEMORY_ING["memory ingestor<br/>Layer 3"]
    AUTH_CHK["RBAC + per-task ACL"]
  end
  subgraph STORES ["Stores"]
    PG[("PostgreSQL + PGroonga<br/>issues / cycles / projects<br/>RLS by tenant_id")]
    RED[("Redis 7<br/>WS rooms / search cache")]
    S3[("S3 + KMS<br/>attachments")]
    NATS[("NATS JetStream<br/>mutation fan-out")]
  end
  subgraph SINKS ["Sinks"]
    memory["memory<br/>Layer 3 ingest / audit"]
    TIME["TIME<br/>billable / non-billable"]
    INV["INV<br/>billable hours -> invoice"]
    OBS["OBS<br/>traces + SLO"]
    CUO["CUO<br/>Notify / review draft"]
  end
  SPA --> WSGW
  MOBILE --> WSGW
  AGENT --> MCP
  WSGW --> SYNC
  GQL --> SYNC
  REST --> SYNC
  MCP --> SYNC
  SYNC --> CRDT
  SYNC --> WF
  SYNC --> AI
  SYNC --> MEMORY_ING
  SYNC --> AUTH_CHK
  SYNC --> PG
  SYNC --> RED
  SYNC --> NATS
  NATS --> WSGW
  CRDT --> PG
  AI --> CUO
  MEMORY_ING --> memory
  WF --> TIME
  TIME --> INV
  SYNC --> S3
  SYNC --> OBS
  classDef planned fill:#cba88a,stroke:#45210e
  classDef store fill:#f5f3ff,stroke:#7c3aed
  classDef sink fill:#f5ede6,stroke:#45210e
  class SPA,MOBILE,AGENT,WSGW,GQL,REST,MCP,SYNC,CRDT,WF,AI,MEMORY_ING,AUTH_CHK planned
  class PG,RED,S3,NATS store
  class memory,TIME,INV,OBS,CUO sink

The four primitives

• Issue (the atomic unit). A discrete piece of work. Has title, description (Yjs), status, priority, assignee, estimate, labels, dependencies, parent issue, cycle binding. Comments are sub-resources.
• Cycle (1-2 week sprint). A time-boxed bucket of Issues. Has start / end dates, target velocity, retro link. Incomplete Issues auto-roll to the next cycle if the team configures it (task pending).
• Project (durable container). A multi-cycle initiative. Has roadmap view, status (planned / active / paused / completed), client visibility flag (visible via PORTAL when the Engagement permits).
• Engagement (the contract). The contract under which a Project is delivered for a Client. Carries the rate card, billable / non-billable rules, ACL. TIME -> INV pulls from here. Vietnamese-consultancy-specific.

Internal components

The cyberos-proj crate is building TASK-PROJ-001 slice 1 - Issue / Cycle / Engagement with RLS, the status FSM, and memory-audit emission. The table lists the module's planned file layout; rows marked (task pending) are not yet built.

Data model

The canonical state is PostgreSQL with row-level security by tenant_id and, for private engagements, additional ACL enforcement by engagement_id membership. Long-form fields are Yjs document snapshots stored as bytea blobs; the active CRDT state lives in Redis for the duration of a session.

erDiagram
  TENANT ||--o{ ENGAGEMENT: "has"
  ENGAGEMENT ||--o{ PROJECT: "delivered as"
  ENGAGEMENT ||--o{ RATE_CARD: "carries"
  PROJECT ||--o{ ISSUE: "contains"
  PROJECT ||--o{ CYCLE: "has"
  CYCLE ||--o{ ISSUE: "schedules"
  ISSUE ||--o{ COMMENT: "has"
  ISSUE ||--o{ DEPENDENCY: "depends on"
  ISSUE ||--o{ LABEL_ASSIGNMENT: "tagged"
  ISSUE ||--o| ASSIGNEE: "assigned to"
  ISSUE ||--o{ ATTACHMENT: "has"
  ISSUE ||--o{ TIME_ENTRY: "logged against"
  PROJECT ||--o{ WORKFLOW: "uses"
  WORKFLOW ||--o{ WORKFLOW_STATE: "defines"
  ISSUE ||--o{ HISTORY_EVENT: "audited"
  ISSUE ||--o{ MEMORY_LINK: "cites"
  CYCLE ||--o| CYCLE_REVIEW: "summarised"
  TENANT {
    uuid id PK
    string slug
  }
  ENGAGEMENT {
    uuid id PK
    uuid tenant_id FK
    uuid client_account_id FK "links to CRM"
    string name
    date start_date
    date end_date
    string acl_mode "open | restricted"
    string billing_mode "T&M | fixed-fee | retainer"
  }
  RATE_CARD {
    uuid id PK
    uuid engagement_id FK
    string role "senior | mid | junior | architect"
    int rate_vnd_per_hour
    int rate_usd_per_hour
    bool billable_default
  }
  PROJECT {
    uuid id PK
    uuid engagement_id FK
    string name
    string status "planned | active | paused | completed"
    bool client_visible
    timestamp created_at
  }
  CYCLE {
    uuid id PK
    uuid project_id FK
    int number
    date start_date
    date end_date
    int velocity_target
    bool autoroll_enabled
  }
  ISSUE {
    uuid id PK
    uuid project_id FK
    uuid cycle_id FK "nullable (backlog)"
    string code "PROJ-1234"
    string title
    bytea description_yjs "Yjs doc snapshot"
    string status "backlog|todo|in-progress|in-review|done|cancelled"
    string priority "urgent|high|medium|low|none"
    uuid assignee_id FK
    int estimate_hours
    int actual_hours
    uuid parent_issue_id FK "nullable"
    timestamp created_at
    timestamp updated_at
    uuid created_by FK
  }
  COMMENT {
    uuid id PK
    uuid issue_id FK
    uuid author_id FK
    bytea body_yjs "Yjs doc"
    timestamp created_at
  }
  DEPENDENCY {
    uuid from_issue_id FK
    uuid to_issue_id FK
    string kind "blocks | relates_to | duplicates"
  }
  LABEL_ASSIGNMENT {
    uuid issue_id FK
    string label
  }
  ATTACHMENT {
    uuid id PK
    uuid issue_id FK
    string filename
    string s3_key
    bigint size_bytes
  }
  TIME_ENTRY {
    uuid id PK
    uuid issue_id FK
    uuid member_id FK
    int minutes
    date entry_date
    bool billable
    string source "TIME"
  }
  WORKFLOW {
    uuid id PK
    uuid project_id FK
    string name
  }
  WORKFLOW_STATE {
    uuid id PK
    uuid workflow_id FK
    string code
    string display_name_vi
    string display_name_en
    int order_idx
    string category "todo | in-progress | done | cancelled"
  }
  HISTORY_EVENT {
    uuid id PK
    uuid issue_id FK
    uuid actor_id FK
    string kind "create | status | assign | comment | ..."
    string from_value
    string to_value
    timestamp ts
    string memory_chain
  }
  MEMORY_LINK {
    uuid issue_id FK
    string memory_path "memories/decisions/..."
    string relation "cites | implements | supersedes"
  }
  CYCLE_REVIEW {
    uuid cycle_id PK
    string draft_markdown
    string sent_markdown
    timestamp generated_at
    timestamp sent_at
  }

Status enum + workflow overlay

The status enum is closed (backlog / todo / in-progress / in-review / done / cancelled). Per-project workflows can rename and re-order the visible states but always map back to a category in the closed set. The category is what drives velocity calculation, auto-roll, and memory ingestion.

API surface

Four surfaces: a WebSocket sync-engine for the SPA, a GraphQL federated subgraph for cross-module queries, an admin REST for migration and bulk import, and an MCP tool catalogue for CUO. All four share the same RBAC predicate.

GraphQL subgraph (federated)

extend schema
 @link(url: "https://specs.apollo.dev/federation/v2.5", import: ["@key", "@requiresScopes"])

type Engagement @key(fields: "id") {
 id: ID!
 name: String!
 clientAccountId: ID!
 startDate: Date!
 endDate: Date
 billingMode: BillingMode!
 projects: [Project!]!
 rateCards: [RateCard!]!
}

type Project @key(fields: "id") {
 id: ID!
 engagementId: ID!
 name: String!
 status: ProjectStatus!
 clientVisible: Boolean!
 cycles(active: Boolean): [Cycle!]!
 issues(filter: IssueFilter, limit: Int = 50, cursor: String): IssueConnection!
}

type Cycle @key(fields: "id") {
 id: ID!
 projectId: ID!
 number: Int!
 startDate: Date!
 endDate: Date!
 velocityTarget: Int
 issues: [Issue!]!
 review: CycleReview
}

type Issue @key(fields: "id") {
 id: ID!
 code: String!
 title: String!
 description: String! # rendered from Yjs doc
 status: IssueStatus!
 priority: IssuePriority!
 assignee: Subject
 estimateHours: Int
 actualHours: Int
 cycleId: ID
 parent: Issue
 children: [Issue!]!
 dependencies: [Dependency!]!
 comments: [Comment!]!
 labels: [String!]!
 attachments: [Attachment!]!
 memoryLinks: [MemoryLink!]!
 history: [HistoryEvent!]!
}

enum IssueStatus { BACKLOG TODO IN_PROGRESS IN_REVIEW DONE CANCELLED }
enum IssuePriority { URGENT HIGH MEDIUM LOW NONE }
enum ProjectStatus { PLANNED ACTIVE PAUSED COMPLETED }
enum BillingMode { T_AND_M FIXED_FEE RETAINER }

type Mutation {
 createIssue(input: CreateIssueInput!): Issue!
 @requiresScopes(scopes: [["proj.write"]])
 updateIssue(id: ID!, patch: IssuePatch!): Issue!
 assignIssue(id: ID!, assigneeId: ID!): Issue!
 moveIssueToCycle(id: ID!, cycleId: ID): Issue!
 addComment(issueId: ID!, body: String!): Comment!
 closeCycle(cycleId: ID!): CycleReview!
 @requiresScopes(scopes: [["proj.cycle.close"]])
}

Sync-engine WebSocket protocol

// Client -> server: optimistic mutation
{
 "op": "issue.update",
 "client_seq": 12834,
 "tenant_id": "01HZ...",
 "issue_id": "01HZ...",
 "patch": { "status": "in-progress", "assignee_id": "01HZ..." },
 "vector_clock": { "spa-stephen-laptop": 47 }
}

// Server -> all room subscribers: canonical state
{
 "op": "issue.state",
 "server_seq": 982341,
 "issue_id": "01HZ...",
 "state": { "status": "in-progress", "assignee_id": "01HZ...", "updated_at": "..." },
 "vector_clock": { "spa-stephen-laptop": 47, "server": 982341 }
}

// Server -> client (conflict, rebase needed)
{
 "op": "rebase",
 "client_seq": 12834,
 "server_state": { ... },
 "reason": "concurrent_modification"
}

MCP tool catalogue

Key flows

Flow 1 - create an issue (sync-engine)

sequenceDiagram
  autonumber
  participant U as Member SPA
  participant WS as WebSocket gateway
  participant S as Sync engine
  participant W as Workflow validator
  participant ACL as ACL check
  participant PG as PostgreSQL
  participant N as NATS JetStream
  participant B as memory audit
  participant OTHER as Other connected SPAs
  U->>U: optimistic local insert (status=todo)
  U->>WS: op:issue.create (client_seq:N)
  WS->>S: dispatch
  S->>ACL: check (subject, action:create, project_id)
  ACL-->>S: allow
  S->>W: validate status transition
  W-->>S: ok
  S->>PG: INSERT issue + history_event
  S->>B: proj.issue_create (chained audit row)
  S->>N: publish proj.issue.{project_id}
  N->>WS: fan-out
  WS->>OTHER: op:issue.state (server_seq:M)
  WS-->>U: op:issue.state (canonical)
  Note over U: local optimistic state reconciled with server-canonical

Flow 2 - concurrent edit + conflict-free merge via Yjs

sequenceDiagram
  autonumber
  participant A as Member A (offline)
  participant B as Member B (online)
  participant Y as Yjs document server
  participant PG as PostgreSQL
  participant N as NATS
  A->>A: edit description offline (vector clock advances)
  B->>Y: op:issue.description.update (online)
  Y->>PG: snapshot description_yjs
  Y->>N: publish issue.description.{id}
  Note over A: A comes back online
  A->>Y: sync (vector clock diff)
  Y->>Y: merge A's edits + B's edits (CRDT)
  Y->>PG: snapshot merged Yjs doc
  Y->>N: publish merged state
  Y-->>A: rebased state
  Y-->>B: rebased state
  Note over Y: no conflict resolution prompt - CRDT semantics handle it

Yjs handles the description / comment-body fields. Scalar fields (status, priority, assignee) use last-write-wins with the server's vector clock as the tiebreaker.

Flow 3 - AI cycle-review draft at cycle close

sequenceDiagram
  autonumber
  participant CL as Cron / cycle close trigger
  participant S as Sync engine
  participant A as AI review generator
  participant AG as AI Gateway
  participant CU as CUO persona
  participant PG as PostgreSQL
  participant N as Notify (CHAT) to AM
  participant AM as Account Manager
  participant B as memory audit
  CL->>S: cycle.end_date reached
  S->>A: assemble inputs (issues, comments, time entries, velocity)
  A->>AG: chat.completions (persona=CUO/COO-skill, cycle review template)
  AG-->>A: draft markdown
  A->>PG: cycle_review.draft_markdown = draft
  A->>N: ping AM "draft ready"
  A->>B: proj.cycle_review_draft
  AM->>S: edit draft
  AM->>S: send to client (via EMAIL)
  S->>B: proj.cycle_review_sent

Flow 4 - blocker detection from comments

sequenceDiagram
  autonumber
  participant U as Commenter
  participant S as Sync engine
  participant BD as Blocker detector
  participant CU as CUO
  participant N as Notify
  participant B as memory audit
  U->>S: add_comment "blocked by waiting on client decision"
  S->>BD: classify comment
  BD->>BD: pattern match ("blocked by", "waiting on", dwell time > 48h)
  BD-->>S: flag {kind:"external_blocker", confidence:0.91}
  S->>CU: enqueue notify to assigner
  CU->>N: ping assigner with issue link
  S->>B: proj.blocker_detected

Flow 5 - estimate calibration nightly batch

sequenceDiagram
  autonumber
  participant CR as Nightly cron
  participant CAL as Calibration engine
  participant PG as PostgreSQL
  participant BR as memory write
  participant DASH as Member dashboard
  CR->>CAL: run for tenant
  CAL->>PG: SELECT estimate, actual hours per member per task_class
  PG-->>CAL: rows
  CAL->>CAL: compute ratio, drift, 7-day moving avg
  CAL->>BR: write calibration summary (memory Layer 3)
  CAL->>PG: write calibration_snapshot rows
  DASH->>PG: query and render the Member's calibration chart

Issue lifecycle

An issue traverses six canonical states (the closed enum). The per-project workflow overlay may rename or re-order the visible states but the underlying category drives velocity, auto-roll, and memory ingestion.

stateDiagram-v2
  [*] --> Backlog: created (no cycle)
  Backlog --> Todo: scheduled into cycle
  Todo --> InProgress: assignee starts
  InProgress --> InReview: PR opened / requesting review
  InReview --> InProgress: reviewer requested changes
  InReview --> Done: approved + merged
  Todo --> Cancelled: discarded
  InProgress --> Cancelled: discarded
  Done --> [*]
  Cancelled --> [*]
  Backlog --> Cancelled: discarded from backlog

Auto-roll behaviour at cycle close

Functional requirements

The CyberOS task catalogue is being rebuilt one feature at a time via the open task-author Agent Skill.

Previous task enumerations were archived 2026-05-14 and are no longer reflected on this page. Specific tasks land here as they are re-authored.

Non-functional requirements

NFRs that PROJ must satisfy. Cross-referenced at nfr-catalog.html#proj.

Dependencies

PROJ depends on AUTH for every call, memory for ingestion + audit, TIME for time entries, AI for CUO features, MCP for tool surfacing, and NATS for fan-out. It is depended on by INV (billable hours roll-up), CRM (deal -> engagement link), KB (project docs), and PORTAL (client-visible Project view at P2+).

graph LR
  subgraph upstream ["PROJ depends on"]
    AUTH["AUTH"]
    memory["memory"]
    TIME["TIME"]
    AI["AI Gateway"]
    MCP["MCP"]
    NATS["NATS JetStream"]
    OBS["OBS"]
  end
  PROJ["PROJ"]
  subgraph downstream ["PROJ is depended on by"]
    INV["INV<br/>billable roll-up"]
    CRM["CRM<br/>deal -> engagement"]
    KB["KB<br/>project docs"]
    EMAIL["EMAIL<br/>thread -> issue"]
    PORTAL["Portal (P2)"]
  end
  AUTH --> PROJ
  memory --> PROJ
  TIME --> PROJ
  AI --> PROJ
  MCP --> PROJ
  NATS --> PROJ
  OBS --> PROJ
  PROJ --> INV
  PROJ --> CRM
  PROJ --> KB
  EMAIL --> PROJ
  PROJ --> PORTAL
  classDef shipped fill:#f5ede6,stroke:#45210e
  classDef planned fill:#fef6e0,stroke:#9c750a
  class memory shipped
  class PROJ,AUTH,TIME,AI,MCP,NATS,OBS,INV,CRM,KB,EMAIL,PORTAL planned

Compliance scope

PROJ is not a regulator's first stop, but it sits inside the audit trail for delivery work and must satisfy ACL, audit, and DSAR obligations.

Risk entries

PROJ-specific risks tracked in the risk register.

KPIs

PROJ rolls up KPIs covering delivery cadence, sync-engine performance, AI feature efficacy, and Member experience.

RACI matrix

PROJ is owned by the COO seat. Today (COO vacant), the CEO is interim accountable; the CTO owns engineering; Account Managers own per-engagement workflow configuration.

R Responsible, A Accountable, C Consulted, I Informed.

Planned CLI surface

A single admin CLI cyberos-proj for tenant operators and an SDK for scripted bulk edits.

1. Create an Engagement

$ cyberos-proj engagement create \
 --tenant cyberskill \
 --client-account acme-vn \
 --name "ACME Q3 platform build" \
 --billing-mode T_AND_M \
 --start 2026-07-01

[engagement created]
 id: 01HZK2...
 client: acme-vn
 billing: T_AND_M
 audit: memory seq=15014 chain=1f2e...3d4c

2. Create a Cycle and bulk-create Issues

$ cyberos-proj cycle create --project pj-acme-platform --number 7 --start 2026-08-04 --weeks 2
[cycle created] id=01HZK3... number=7 dates=2026-08-04 / 2026-08-17

$ cyberos-proj issue bulk-create --cycle 01HZK3... --file backlog.yaml
[bulk-create] parsed 12 issues
[bulk-create] PROJ-1247 "Auth integration" -> assignee=linh@...
[bulk-create] PROJ-1248 "Migration runbook" -> assignee=tu@...
[bulk-create] ... 10 more
[bulk-create] 12 created, 0 errors
[audit] memory seq=15018 chain=...

3. Close a Cycle (auto-generate review draft)

$ cyberos-proj cycle close --id 01HZK3...

[cycle close] 12 issues - 8 done, 3 rolled, 1 cancelled
[review draft] generated via CUO/COO-skill
[review draft] saved to ./cycle-7-review.md (124 lines)
[notify] Account Manager pinged in CHAT
[audit] memory seq=15042 chain=...

4. Move all in-progress issues to the next cycle

$ cyberos-proj cycle rollover --from 01HZK3... --to 01HZK4... --status in-progress

[rollover] 3 issues moved
[rollover] PROJ-1249, PROJ-1251, PROJ-1255
[audit] memory seq=15045 chain=...

5. Estimate calibration report

$ cyberos-proj calibration --member linh@cyberskill.world --range 90d

member: linh@cyberskill.world
task_class estimates actual_avg ratio trend
backend.feature 18 1.18x +18% improving
infra.config 9 0.96x -4% stable
qa.test_plan 12 1.42x +42% widening
overall 39 1.18x +18% improving

6. Export a DSAR bundle

$ cyberos-proj dsar-export --subject linh@cyberskill.world --output linh-proj.zip

[dsar] subject: linh@cyberskill.world
[dsar] issues: 218 (authored), 612 (assigned)
[dsar] comments: 1,894
[dsar] history: 4,217
[dsar] written: linh-proj.zip (38 MB)

7. Replay a sync-engine conflict for debug

$ cyberos-proj sync replay --tenant cyberskill --since 1h --filter "issue.update"

[replay] 47 mutations, 2 rebases, 0 lost
[rebase] PROJ-1247 client_seq=18 server_seq=98234 reason=concurrent_modification
[rebase] PROJ-1255 client_seq=22 server_seq=98241 reason=concurrent_modification

Phase status & estimates

• Status: planned - P1; slice 1 in build
• Est. LoC: ~11,000 - Rust + TS + Yjs
• Planned tests: 140+ - including CRDT property-tests
• External libs: ~14 - axum, sqlx, ywasm, NATS
• CLI subcommands: ~22 planned - cyberos-proj
• P1 budget: ~$80/mo - Fargate + RDS + Redis + NATS

References

• Cross-module join contracts: the "Orchestration spine" section above - the canonical table that every counterparty module reads from.
• Engagement economic model: the "Engagement economics" section above - 3 billing modes + rate-card YAML + billable cascade.
• Memory-anchored decisions: the "Memory-anchored decisions" section above - citation relations + decision-to-issues sequence + dual-write audit chain.
• Liquid-Glass UI exemplar: the "Liquid-Glass UI surfaces" section above - 4 canonical surfaces + tokens.proj.css overlay + accessibility commitments.
• Memory auto-sync vision: MEMORY_AUTOSYNC_DESIGN.md §5 (capture surfaces) - PROJ mutations are one of the four canonical capture inputs to the local memory.
• task authoring discipline: modules/skill/task-audit/AUTHORING_DISCIPLINE.md - PROJ tasks re-authored one-by-one via the task-author Agent Skill; "(task pending)" markers are intentional placeholders.
• Build-readiness audit: archive/2026-05-14/AUDIT_AND_PLAN.md (archived; see cyberos/CHANGELOG.md) - PROJ placed at P1 mid in the P1 sequence (after the CHAT decommission gate clears at P0 exit).
• Research review: archive/2026-05-14/RESEARCH_REVIEW.md (archived; see cyberos/CHANGELOG.md) - the reviewer flagged the consultancy-Engagement primitive as the highest-impact differentiator vs Linear/Jira; the orchestration-spine framing addresses §6 "what makes this not a feature?".
• Cross-module page links: memory.html, skill.html, auth.html, chat.html, time.html, inv.html, crm.html, kb.html, rew.html, okr.html, portal.html
• Linear sync-engine: Tuomas Artman, "Scaling the Linear Sync Engine" (2023 talk) - informs the optimistic / rebase pattern.
• Yjs CRDT framework: github.com/yjs/yjs; ywasm Rust binding.
• PGroonga + TinySegmenter: Postgres full-text search with VN tokenisation; baseline recall >= 90% on a 50-query corpus.
• NATS JetStream: message-streaming layer for WebSocket fan-out.
• Apollo Federation v2.5: subgraph composition spec; PROJ exposes the federated subgraph that every cross-module GraphQL query goes through.
• Vietnam PDPL (Law 91/2025): Art. 7 (data-subject rights), Art. 14 (DSAR), Art. 20 (security obligations).
• Architecture context: infrastructure.html#proj.

Personas & skill bundles that touch PROJ

PROJ is the work-tracking surface most CUO personas read from and write to. The catalog spans 47 personas with 220+ workflows and their paired author/audit skill bundles; the ones below are PROJ-affined in particular.

Persona affinities (8 of 47):

• chief-operating-officer - weekly cadence + cycle reviews + delivery review
• chief-product-officer - roadmap-planning + feature-prd-intake
• chief-technology-officer - deploy-readiness-review + post-incident-review
• chief-of-staff - decision-log-keeping + special-project-charter
• chief-transformation-officer - per-program-charter
• chief-innovation-officer - per-innovation-charter
• chief-automation-officer - per-automation-charter
• chief-restructuring-officer - per-turnaround-plan

Skill-bundle reads & writes:

• task-author + audit - drafts a task Markdown that becomes a PROJ Issue on commit
• implementation-plan-author + audit - explodes a task into a child-issue tree
• project-plan-author + audit - per-program project plan written to PROJ Cycles
• stage-gate-author + audit - per-cycle exit-gate adjudication
• retrospective-author + audit - end-of-cycle retro draft
• postmortem-author + audit - post-sev1/sev2 blameless post-mortem

Previous module: EMAIL | Next module: TIME

Changelog

History lives in the changelog; this page describes only the current state.

Generated from services/proj/docs/index.md — edit the markdown source, not this file (TASK-DOCS-002).