# Company world model, capabilities, and intelligence

This document is the **contract** for how “what the company knows” and “what runs” fit together. It exists so the console, agents rail, and issues stay **one game**: Postgres Company OS keyed by **`company_id`**, not a parallel in-memory product.


**Knowledge representation (JSON-LD):** [knowledge-representation.md](./knowledge-representation.md) — `@context`, table→type map, promotion ladder ↔ `memory_edges`. Export one memory: `GET /api/company/companies/{company_id}/memory/{memory_id}/export-jsonld`.

---

## 1. World model (company) — canonical operational graph

Treat **Postgres Company OS** as the **single source of operational truth** for a company:

| Area | Role in the graph |
|------|-------------------|
| **Tasks** | Work units: state, checkout, `requires_human`, attachments, `context_notes`, **`capability_refs`** (links to skills/SOPs/tools/packs/agents), spawn/handoffs, spend links. |
| **Runs / telemetry** | Honest signals: terminal status, tool usage, logs — surfaced on tasks and in governance-style events where wired. |
| **`company_memory_entries`** | Durable shared and agent-scoped facts; search/append via API and tools. |
| **`companies.context_markdown`** | Company-wide narrative the LLM layer always sees (with memory and task context). |
| **`GET …/tasks/:id/llm-context`** | Composed **read model** for agents: context markdown, memory pool, task block, workforce profile, headings/TOC as implemented. |
| **Goals, governance events, spend** | Alignment, policy trail, and cost — same `company_id`. |

Anything labeled **“intelligence”** in product terms should **read and write through this graph** (or explicitly **sync into** it), not maintain a second ledger the UI pretends is equally real.

---

## 2. Capabilities — atomic building blocks

These are **already modular** in the product; the rule is to **link them into the world model**, not float them beside it:

- **Tools & skills** — registered and invoked with company/task context.
- **Packs** — bootstrap templates; after import, **roster and skills** should resolve to **Postgres** (`company_agents`, adapter config, etc.).
- **Workforce agents** — rows with roles, budgets, profiles; **`llm-context`** and task checkout should resolve **persona → agent row** where possible.
- **SOPs / playbooks** — procedures tied to **projects and tasks** (see [playbooks-projects-and-visions.md](./playbooks-projects-and-visions.md)).

**Direction:** task and agent APIs (and UIs) should carry **explicit references** (IDs, personas, skill refs) so the graph is queryable — “who is on this,” “what skills apply,” “which SOP governs this stream.”

**Implemented in tree:** `tasks.capability_refs` (JSONB array of `{ "kind", "ref" }` or create-body strings normalized to `kind: skill`). Set at **create**, **PATCH `/api/company/tasks/{id}/context`**, and **bundle import/export**; copied to **spawned subtasks**; merged into **`GET …/tasks/{id}/llm-context`** and the **Intelligence** workflow feed when updated (`task_capability_refs_updated`). **Pack bridge:** `POST …/import-paperclip-home` pulls on-disk agents/skills into Postgres for the company.

**Paperclip → Postgres (goals & DRIs):** `goals.paperclip_goal_id` + `paperclip_snapshot` for upserts; **`POST /api/company/companies/{id}/sync/paperclip-goals`** (optional JSON `{ "goals": [...] }`, or empty body when `hsm_console` runs with in-process `IntelligenceLayer`); **`POST …/sync/paperclip-dris`** same for `{ "dris": [...] }`. **`dri_assignments`** table + **`GET/POST …/dri-assignments`** and **`PATCH/DELETE …/dri-assignments/{row_id}`** for first-class org DRIs (including manual rows).

---

## 3. Intelligence layer — two APIs, one truth

| Surface | Scope | Use |
|---------|--------|-----|
| **`/api/company/companies/{company_id}/…`** | Per company | **Canonical**: goals, tasks, memory, spend, intelligence summary, `llm-context`, etc. |
| **`/api/paperclip/*`** (proxied in dev) | Global / in-memory demo | **Optional**: composition, routing experiments, demos — **not** a second company dashboard of record. |

**Allowed patterns:**

1. **Embed** composition/routing **inside** Company OS (per `company_id`) so all state lives in Postgres; or
2. **Sync** Paperclip-style state **into** Postgres (goals, signals, DRIs) so operators still have **one** store and **one** UI truth.

**Anti-pattern:** two first-class UIs that each imply their own goals/signals/registry without migration or sync — that splits hierarchy (alignment, backlog, who is on what) across “Postgres truth” and “optional global layer.”

Workspace **Intelligence** in the company console should prefer **`GET …/intelligence/summary`** (and related company routes), not Paperclip-only views.

---

## 4. Interfaces — edges of the same model

| Interface | Expectation |
|-----------|-------------|
| **Company console** | Reads/writes **`/api/company/…`** for the selected company; copy should not imply a global parallel state is authoritative. |
| **Agents rail** | Chat and task actions **mutate** the same task graph (checkout, notes, runs) for that `company_id`. |
| **Issues / my-work** | Same task list and states as the API; no shadow issue system. |

If a feature cannot point at a **`company_id`** and a concrete row or API path, it is not yet part of the world model — it is integration or demo debt.

---

## 5. Implemented alignment contract

This section is the quick check for whether a feature helps models, harnesses, and systems stay "likewise" — seeing the same world through different interfaces instead of inventing parallel realities.

| Contract | Implemented surface | Why it matters |
|----------|---------------------|----------------|
| **Model context contract** | `GET /api/company/tasks/:task_id/llm-context` in `src/company_os/agents.rs` returns `company_id`, `hsmii_home`, `context_notes`, `capability_refs`, workspace paths, `agent_run_profile`, `combined_system_addon`, section byte counts, and `context_manifest`. | A model starts from the same company/task graph the UI and tools use. It can see explicit memory/tool instructions rather than guessing from chat. |
| **Memory contract** | `company_memory_entries` plus `company_memory_search` / `company_memory_append` in `src/tools/company_os_tools.rs`; shared, agent, and broadcast scopes are exposed in `llm-context`. | Shared facts compound across agents; private notes stay scoped; urgent company lines can be broadcast without becoming invisible side-channel state. |
| **Capability contract** | `tasks.capability_refs` (`skill`, `sop`, `tool`, `pack`, `agent`, etc.) set through task APIs/imports and rendered in `llm-context` + workflow feeds. | Models and harnesses can reason over explicit procedures and tools, not prose-only hints. |
| **Governance / DRI contract** | `requires_human`, `dri_assignments`, `governance_events`, run feedback, and intelligence summary workflow feed. | Escalation and accountability become rows with owners and evidence, not vibe-based chat conclusions. |
| **Intelligence sync contract** | Paperclip-style goals/DRIs sync into Postgres via `paperclip_goal_id`, `paperclip_snapshot`, `sync/paperclip-goals`, `sync/paperclip-dris`, and manual DRI CRUD. | External intelligence can compose and propose while Company OS remains the ledger. |
| **Harness contract** | `hsm-eval`, `hsm_meta_harness`, `hsm_outer_loop`, Python `scripts/meta-harness`, `scripts/refiner-jsonl-pass.py`, and `scripts/meta-harness/company_os_refiner_pass.py` write artifact trees, `turns_hsm.jsonl`, `company_os_turns.jsonl`, candidate configs, and deltas. | Evals and live agent-chat smokes improve benchmark/runtime policy through reviewable evidence; they do not silently mutate live runtime behavior. |
| **Eval-pack contract** | `schemas/company_eval_pack.v1.json`, `scripts/meta-harness/pack_loader.py`, and `scripts/meta-harness/kpi_verifier.py` let each company declare tasks, personas, scorer bindings, KPI assertions, and promotion thresholds. | Company-specific "what good looks like" stays declarative while runner, tracing, verifier registry, frontier search, and promotion gates remain shared platform primitives. |
| **Hosted / LLM documentation contract** | `docs-site/sync-manifest.json` mirrors selected docs into VitePress pages and `/llm/*.md` files. | Agents can fetch the same architecture contract operators read, reducing prompt drift across tools and sessions. |

### Four knowledge layers

Treat company knowledge in four layers (constitution → operational → procedure → evidence). Full table, JSON-LD mapping, DRI/verifier/ledger rules, and context/review/compaction policy: **[knowledge-representation.md](./knowledge-representation.md#four-knowledge-layers-recommended-policy)**.

### Promotion ladder

Use this ladder whenever a new intelligence feature, harness result, or agent behavior is introduced:

1. **Observe:** capture the signal in a trace, task note, governance event, memory row, or run artifact.
2. **Bind:** attach it to a company, task, DRI, goal, capability ref, or harness config path.
3. **Expose:** make it visible through `llm-context`, `intelligence/summary`, task APIs, or an eval artifact index.
4. **Verify:** run the relevant smoke or benchmark and record the artifact path / logs.
5. **Promote:** only after verification, map the change into runtime config, prompt policy, tool allowlist, memory policy, or docs.

If a step cannot be completed, label the work as **integration debt** rather than "implemented intelligence."

### Red flags

- A model answer depends on state that is not in `llm-context`, memory, task notes, or a declared file path.
- A dashboard shows goals, agents, DRIs, or task state without a `company_id` and Company OS API path.
- A harness `best_config.json` is treated as production behavior without a runtime mapping.
- A high-stakes action completes without `requires_human`, DRI, governance, or run evidence when confidence is low.
- A capability is described in copy but absent from `capability_refs`, tool registry, skills, SOPs, or pack import.

---

## See also

- [Intelligence layer & DRI alignment](./intelligence-layer-dri-alignment.md) — composer vs ledger vs edge (DRIs); integration checklist for external intelligence.
- [Company eval packs and meta-harness scoring](./eval-pack-and-scoring-contract.md) — declarative per-company task/KPI packs and shared scorer/promotion contract.
- [HSM-II field coordination](../HSMII_FIELD_COORDINATION.md) — stigmergic field, model/harness/runtime contract, and ratchet gates.
- [Memory, workspace attachments, shared context](../issues/memory-workspace-shared-context.md) — `company_memory`, `context_notes`, `llm-context`, tools.
- [Playbooks, projects, and visions](./playbooks-projects-and-visions.md) — how SOPs sit on the task/project graph.