# Changelog

All notable changes to Priority Forge are documented here. Format follows
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); the project does
not yet use SemVer-style version tags since v4 — entries are grouped by
the **Plan** the work belonged to, with commit-sha anchors. The v4.0.0
baseline is treated as "before Plan 1."

## Unreleased — Plan 2 polish wave 2

Additive improvements after Plan 2's first end-to-end live deployment.
Each lands as its own commit; nothing breaks existing usage.

### Added
- **`xmem_get_current_focus`** now returns separate `agents` (currently
  active) and `idleAgents` (observed but currently idle) keys instead
  of a single map with `null` values for idle agents. Cleaner signal
  for "who is doing what right now." (`4fa5fa8`)
- **`shared_task_timeline`** — new MCP tool + REST endpoint that returns
  a chronological narrative view of a SharedTask's lifecycle, with
  relative timestamps (`"5m ago"`) and human-readable descriptions
  (`"alice@team (originator) claimed \"Fix auth\""`). Coexists with
  `shared_task_history` (raw structured data). (`edd2bc2`)
- **`scripts/bootstrap-hub.ts --rotate-only`** — symmetric to
  `--add-only`. Refuses to register new agents; only rotates tokens
  for already-known agents. Compromise-response use case. Mutually
  exclusive with `--add-only`. (`7d5f4bb`)
- **`scripts/bootstrap-hub.ts --add-only`** — for incremental teammate
  onboarding without rotating other teammates' tokens. (`7596c1f`)

### Changed
- **`xmem_get_status`** response now includes `pgvectorConnectionStringSet`,
  `pgvectorAgentTokenSet`, `pgvectorCredsComplete` for parity with the
  existing `xmem*Set` fields. Quick one-line `curl /xmem/status`
  diagnostic. (`cac1dce`)
- **`npm run build`** and **`npm run dev`** automatically build the
  `priority-forge-hub` workspace package first via the new `build:hub`
  script. Fresh clones no longer hit a `SyntaxError: Unexpected token
  'export'` from the hub's raw TypeScript main. (`afc916d`)

### Fixed
- **Bridge memory-plane emission gap** — the orchestration bridge
  previously called `storage.createTask` / `storage.claimTask` directly,
  bypassing `syncEmitter` (which is wired from `handler.ts` only). Net
  effect: cross-forge `shared_task_*` lifecycle was invisible to the
  memory plane — only `task_completed` events surfaced. The bridge
  now emits two flavors of observations: `shared_task_*`
  `TeamMemoryEvent`s directly via `getMemoryHub().write()`, and the
  full `task_created` / `task_selected` / `task_completed` triplet for
  the local projection via `syncEmitter`. Verified live: full 6-event
  lifecycle now captured per shared-task cycle. (`3816bfa`)

## Plan 2 — SharedTask + OrchestrationHub (single-claim lease)

The cross-forge work-coordination layer. Adds a hub-canonical
`SharedTask` entity, atomic single-claim lease semantics, and a
host-side bridge that materializes/archives local Task projections.

### Added
- **`OrchestrationHub` interface** alongside `MemoryHub`. Adapters
  `implements MemoryHub, OrchestrationHub`. Hub package is now a
  two-plane substrate. (`48cd4e2`)
- **`SharedTask` entity** — identity + audit only (id, teamId, title,
  description, originator, currentClaim, claimHistory, status). Hub
  boundary guardrail codified at the schema level. (`48cd4e2`)
- **9 MCP tools + REST routes** — `shared_task_create` / `publish` /
  `claim` / `release` / `renew_lease` / `get` / `list` /
  `get_my_claims` / `history`. (`3e97ff3`)
- **Auto-release** — `complete_task` on a Task with `sharedTaskId`
  fires `orchestrationHub.release()` fire-and-forget. Users don't
  have to remember a second call. (`3e97ff3`)
- **Auto-renew heartbeat** — 15-min interval renews leases on all
  in-progress shared-task projections; marks local task as `blocked`
  with a note when the lease is lost. (`3e97ff3`)
- **Token-gated writes (pgvector only)** — `agent_identities` table
  + SHA-256 token verification before every write / create / claim /
  release / renewLease. Opt-in via `agentToken` in
  `MemoryHubConfig.pgvector`. Includes `xmem_register_agent` MCP
  tool for bootstrap. (`8b8da43`)
- **`xmem_get_current_focus`** snapshot tool — reduces the recent
  event stream into a per-agent current-focus map. (`8b8da43`)
- **pgvector orchestration impl** — atomic CAS via single
  `UPDATE...WHERE` predicate. (`48cd4e2`)
- **dryrun orchestration impl** — in-process Map-based CAS for
  single-process testing. (`48cd4e2`)
- **noop + xmem orchestration stubs** — `supportsOrchestration:
  false`; all methods return `unsupported_backend`. xmem stays
  stubbed until xtrace.ai's API deploys. (`48cd4e2`)
- **`scripts/bootstrap-hub.ts`** — one-shot bootstrap automation:
  applies schemas, registers agents (SHA-256 hashed tokens), runs
  6-step end-to-end smoke including a negative `verifyAgent` check.
  (`1d7e6af`)
- **`docs/HUB_DEPLOYMENT.md`** — RDS provisioning runbook, bootstrap
  usage, secret distribution guidance, teardown commands. (`1d7e6af`)
- **`packages/priority-forge-hub/ARCHITECTURE.md`** — full role +
  responsibility breakdown, system mermaid diagram, SharedTask
  lifecycle sequence diagram, backend support matrix, hardening
  setup, lead-engineer framing (info vs work flows). (`b6d2201`)
- **Orchestration contract test** — parameterized 24-test suite
  against dryrun + pgvector (when `MEMHUB_PGVECTOR_URL` is set);
  plus noop + xmem stubbed-unsupported assertions. (`8e1a9dd`)
- **`Task.sharedTaskId?` field** — optional link from a local Task
  to its hub-canonical SharedTask. (`41094c0`)
- **`src/orchestration/shared-tasks.ts`** — host-side bridge module.
  Materializes local Task projections on claim, archives on
  release, maps PF outcomes ↔ hub `ClaimOutcome`. (`41094c0`)
- **`storage.getTaskBySharedTaskId` + `storage.linkSharedTask`** —
  new storage interface methods. (`41094c0`)
- **`PgvectorMemoryHub` re-exported** from the hub package's public
  surface so the bootstrap script can construct it directly.
  (`fced33e`)
- **Hub package's `main`/`types`** point at compiled `./dist/index.js`
  so `node dist/index.js` (production systemd path) loads correctly.
  (`1992116`)

### Pinned design decisions (all from the design discussion)
- Single-claim lease (Symphony-style), TTL-based, lazy expiry
- Hub-canonical `SharedTask`; PF materializes a transient projection
  on claim
- Stacked schema-level guardrails — hub stores identity + audit only;
  never task content or learning signals
- Separate `OrchestrationHub` interface from `MemoryHub`
- xmem orchestration stubbed `unsupported_backend` pending xtrace.ai
  API deploy
- npm workspaces (asymmetric layout — PF at root, hub at `packages/`)
- TeamId = `team_<slug>`, agentId = work email by convention (the hub
  stores them as opaque strings)

## Plan 1 — Extract `memory-hub` to workspace package

Made `priority-forge-hub` a reusable package; eliminated the two
upward imports that had been preventing extraction.

### Changed
- **Repo layout**: `src/integrations/memory-hub/` → `packages/priority-forge-hub/`.
  Asymmetric monorepo via npm workspaces — PF stays at repo root,
  only the hub moves. (`372aa65`)
- **Inverted upward imports**: `subscriber.ts` no longer imports
  `loadTeamPulseConfig` from `'../../sync'`; `blocker-emitter.ts`
  no longer imports `storage` from `'../../storage/jsonStorage'`.
  Bridge provides `TaskProvider` + `EmitterGateController` at
  construction. (`372aa65`)
- **`createMemoryHubIntegration({...deps})`** factory replaces
  separate `attachMemoryHubToEmitter` + `startReaderIfEnabled`
  exports. Returns `{reader, rederive(), detach()}` handle.
  (`372aa65`)
- **`blocker-emitter.ts`**: module-level mutable state (`inFlight`,
  `edgeState`) encapsulated in the closure returned by
  `createBlockerEmitter`. (`372aa65`)
- **Hub-boundary guardrail** codified in `CLAUDE.md` ahead of
  Plan 2's expansion. (`372aa65`)

### Pinned design decisions
- Asymmetric workspace layout (avoid shuffling 50+ files of PF)
- npm workspaces (already on npm; pnpm migration would be churn)
- Single factory shape `createMemoryHubIntegration({deps})` over
  separate attach + setter
- Hub-owned `TaskProvider` + `EmitterGateController` interfaces
- Hub package name: `priority-forge-hub`, workspace-only, unpublished
- Runtime state paths unchanged (`~/.priority-forge/xmem.json`,
  `xmem-dryrun.jsonl`)

## v4.0.0 baseline (pre-Plan-1)

The system before the hub extraction work. Featured:
- MCP server + REST API on port 3456
- XGBoost-trained priority ranker (heuristic weights baseline)
- Workspace management with freshness/dormancy scoring (V4.3)
- V4.0 work-duration tracking (`startedAt` capture via `claimTask`)
- V4.1 selection events with pairwise preferences
- V4.2 synthesized selection on direct `not_started → completed`
- V3.2 drag-reorder online learning
- Cursor + Codex plugins for agent rule injection
- systemd / launchd persistent service install

Commits in this baseline range include `6b774fa`, `f2fac56`,
`afee5d5`, `b5c8514`, `b81d552`, `6a88eb0`, `c7783e6` and earlier.
