@dealdesk/server 2026.527.0-canary.0

package/skills/dealdesk-dev/SKILL.md

@@ -0,0 +1,103 @@
+---
+slug: dealdesk-dev
+name: deal-desk-dev
+required: false
+description: >
+  Develop and operate the DealDesk application. Use when changing DealDesk
+  routes, schema, seeds, tools, UI pages, Quick Hire behavior, role templates,
+  or PE workflow tests.
+domain: deal-desk
+---
+
+# DealDesk Dev Skill
+
+Use this skill when working on the DealDesk application itself.
+
+DealDesk is a PE-focused layer in this repository. It includes thesis setup, target tracking, intermediary coverage, contact enrichment, role templates, Quick Hire, and DealDesk-specific agent instructions.
+
+## Key Areas
+
+- DB schema: `packages/db/src/schema/deal_desk.ts`
+- Server routes: `server/src/routes/deal-desk.ts`
+- Server tools: `server/src/deal-desk/tools/`
+- Role templates: `server/src/deal-desk/seeds/role-templates.ts`
+- Quick Hire UI: `ui/src/pages/deal-desk/QuickHire.tsx`
+- DealDesk pages: `ui/src/pages/deal-desk/`
+- DealDesk API client: `ui/src/api/dealDesk.ts`
+- Tests: `server/src/routes/deal-desk.test.ts`, `packages/db/src/deal-desk.test.ts`, and focused UI tests where available
+
+## Engineering Rules
+
+- Keep every DealDesk entity company-scoped.
+- Preserve PE language: thesis, target, intermediary, owner, CEO, contact, outreach draft, pipeline, partner review.
+- Prefer structured fields over prose blobs.
+- Add migrations for persisted schema changes.
+- Keep role templates idempotent through the seeder.
+- Do not resurrect retired memo-only flows.
+- Keep Quick Hire simple: name, title, instructions, budget, and attached DealDesk skills.
+
+## Development Workflow
+
+1. Read the relevant schema, route, API client, and UI page before editing.
+2. Update contracts across DB, server, shared validators/types, and UI together.
+3. Add or adjust focused tests around the changed behavior.
+4. Run the smallest meaningful verification first.
+5. Run typecheck for touched packages before handoff.
+
+## Common Tasks
+
+### Add A DealDesk Field
+
+- Update `packages/db/src/schema/deal_desk.ts`.
+- Generate or add the migration.
+- Update route serialization and validation.
+- Update the UI form/table/card.
+- Add DB and route tests.
+
+### Add A DealDesk Tool
+
+- Add the handler under `server/src/deal-desk/tools/`.
+- Export/register it in `server/src/deal-desk/tools/index.ts`.
+- Enforce company scoping and input validation.
+- Return structured output with IDs and warnings.
+- Add tests for auth, validation, dedupe, and success.
+
+### Update Role Templates
+
+- Edit `server/src/deal-desk/seeds/role-templates.ts`.
+- Keep prompts concise and role-specific.
+- Mention relevant DealDesk skills.
+- Run server startup/seed tests if touched.
+
+### Update Quick Hire
+
+- Keep the UX minimal.
+- Send instructions through `instructionsBundle`, not legacy prompt fields.
+- Attach the DealDesk skill set through `desiredSkills`.
+- Verify the payload includes budget, role, adapter config, instructions, and desired skills.
+
+## Verification Checklist
+
+Use focused checks that match the change:
+
+```bash
+pnpm vitest run server/src/routes/deal-desk.test.ts packages/db/src/deal-desk.test.ts
+pnpm --filter server typecheck
+pnpm --filter ui typecheck
+```
+
+For wider changes, add:
+
+```bash
+pnpm test
+pnpm build
+```
+
+## Handoff Standard
+
+Report:
+
+- What DealDesk workflow changed.
+- Which records/routes/UI surfaces are affected.
+- Tests and typechecks run.
+- Any remaining product or data migration risk.

package/skills/diagnose-why-work-stopped/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: diagnose-why-work-stopped
+description: >
+  How to handle "why did this work stop / why is this looping?" assignments.
+  Forensics first on the named tree, surface the exact stop-point, frame the
+  fix as a general product rule that respects three invariants (productive
+  work continues, only real blockers stop work, no infinite loops), and
+  deliver a plan — no code changes — gated by board/CTO approval before
+  child issues are created. Use whenever the issue title or body asks for
+  forensics on a stalled, looping, or "went too deep" tree.
+---
+
+# Diagnose Why Work Stopped
+
+A repeatable procedure for the recurring class of issues where the user (or a manager) points at a stalled / looping / over-recovered issue tree and asks "why did this stop / why is this looping / how do we make sure this doesn't happen again?"
+
+This skill is **diagnostic + product-design**, not engineering. The output is a written root cause and an approved plan. No code changes leave this skill.
+
+Canonical execution model: read `doc/execution-semantics.md` before diagnosing or proposing a new liveness/recovery rule. Use that document as the source of truth for status, action-path, post-run disposition, bounded continuation, productivity review, pause-hold, watchdog, and explicit recovery semantics. If the investigation finds a true product-rule gap, the plan should say whether `doc/execution-semantics.md` needs a matching update.
+
+## When to use
+
+Trigger on an assignment whose title or body matches any of:
+
+- "why did this work stop", "why did this stall", "why did this just stop"
+- "infinite loop", "looping", "spinning", "going too deep", "recovery went too deep"
+- "liveness — what happened here", "this tree stopped working", "stuck"
+- "approach it from a product perspective", "general product principle / rule"
+- An attached link to a specific stalled / looping / over-recovered issue tree
+
+Also use when the user asks for forensics, root cause, or a write-up *before* any product change.
+
+## When NOT to use
+
+- The assignment asks you to ship a code change directly. Use normal engineering flow.
+- The assignment is a normal bug report against a specific feature. Use normal investigation.
+- You are the original implementer being asked to fix your own bug. Use normal debugging.
+
+## Three invariants you must preserve
+
+Every diagnosis and every proposed rule must hold these three invariants together. The user has restated them on at least four issues; treat them as load-bearing:
+
+1. **Productive work continues.** Agents that have a clear next action must keep working without needing the user to wake them. ([PAP-2674](/PAP/issues/PAP-2674), [PAP-2708](/PAP/issues/PAP-2708))
+2. **Only real blockers stop work.** Stops happen when something genuinely cannot proceed (missing approval, missing dependency, human owner). Pseudo-stops (in_review with no action path, cancelled leaves, malformed metadata) must be detected and routed, not left silent. ([PAP-2335](/PAP/issues/PAP-2335), [PAP-2674](/PAP/issues/PAP-2674))
+3. **No infinite loops.** Stranded-work recovery and continuation loops must be bounded and distinguishable from genuinely productive continuation. ([PAP-2602](/PAP/issues/PAP-2602), [PAP-2486](/PAP/issues/PAP-2486))
+
+If a proposed rule violates any of the three, drop it or rework it. State explicitly in the plan how each invariant is held.
+
+## Procedure
+
+### 0. Read the current execution contract
+
+Before walking the tree, read `doc/execution-semantics.md` and keep its terms intact:
+
+- live path / waiting path / recovery path
+- post-run disposition: terminal, explicitly live, explicitly waiting, invalid
+- bounded `run_liveness_continuation`
+- productivity review vs liveness recovery
+- active subtree pause holds
+- silent active-run watchdog
+
+Do not invent a new rule until you can state how it differs from the current execution semantics document.
+
+### 1. Forensics on the named tree — before anything else
+
+Do this in the same heartbeat. Do not propose a rule until you have a concrete stop point.
+
+- Open the linked issue (and its blocker chain, parents, recovery siblings, recent runs).
+- Walk the tree node-by-node and find the exact issue + state combination that stops the world. Common shapes seen in the company so far:
+  - `in_review` with no typed execution participant, no active run, no pending interaction, no recovery issue ([PAP-2335](/PAP/issues/PAP-2335), [PAP-2674](/PAP/issues/PAP-2674)).
+  - `in_progress` after a successful run with no future action path queued ([PAP-2674](/PAP/issues/PAP-2674)).
+  - Blocker chain whose leaf is `cancelled` / malformed / cross-company-inaccessible ([PAP-2602](/PAP/issues/PAP-2602)).
+  - `issue.continuation_recovery` waking the same issue >N times after successful runs ([PAP-2602](/PAP/issues/PAP-2602)).
+  - Stranded-work recovery treating its own recovery issues as more recoverable source work ([PAP-2486](/PAP/issues/PAP-2486)).
+- Quote the evidence: run ids, comment timestamps, status transitions. "Inferred" is acceptable only when an API boundary blocks direct evidence — say so explicitly and mark the claim provisional ([PAP-2631](/PAP/issues/PAP-2631)).
+
+Respect the API boundary. If the linked issue is in another company and your agent token returns 403, do not bypass scoping. Either request a board-approved diagnostic path or proceed from inferred PAP-side evidence and label it.
+
+### 2. Survey recent related work
+
+Before proposing a new product rule, read what already shipped this week in the same area. The user has explicitly called this out: ([PAP-2602](/PAP/issues/PAP-2602)) "review our recent work on liveness that we shipped in the last couple of days." A new rule that contradicts code merged 48 hours ago is rework, not improvement.
+
+Quick survey:
+- Recent merged PRs in the affected area.
+- Recent done issues whose title mentions liveness, recovery, productivity, continuation, or the affected subsystem.
+- Any active plan documents on parent issues. The fix may belong as a revision to an existing plan, not as a new top-level proposal.
+
+State in the forensics: "I reviewed X, Y, Z. The new gap is …"
+
+### 3. Classify each non-progressing issue in the tree
+
+For every issue in the affected tree that is not `done` / `cancelled` / actively running, decide:
+
+- **Truly needs human or board intervention** — name the owner and the action.
+- **Agent-actionable but not currently routed** — name the rule that would have routed it, and the agent that should have been waked.
+- **Already covered** — point at the active run, queued wake, recovery issue, or pending interaction.
+
+This is the table the user has asked for repeatedly ([PAP-2335](/PAP/issues/PAP-2335)). Without it the plan is abstract.
+
+### 4. Frame as a general product rule
+
+The user does not want a one-off patch on the named tree. They want the rule. Two checks:
+
+- The rule is **stated as a contract**, not as an if/else patch. Example contract: "every agent-owned non-terminal issue must finish each heartbeat with a terminal state, an explicit waiting path, or an explicit live path" ([PAP-2674](/PAP/issues/PAP-2674)).
+- The rule is reconciled against `doc/execution-semantics.md`. Prefer citing and applying the existing contract; propose a document change only when the current doc is incomplete or contradicted by accepted/implemented behavior.
+- The rule **explicitly preserves the three invariants** above. Show the work.
+
+If the rule would have blocked a recent productive run from succeeding, drop or narrow it.
+
+### 5. Plan, do not code
+
+Write the plan into the issue's `plan` document. Cover:
+
+- Forensics summary (root cause + evidence).
+- The general product rule, stated as a contract.
+- Whether the existing `doc/execution-semantics.md` contract already covers the case, or what exact documentation update is needed.
+- Phased subtasks: typically `Phase 0` resolves the named live tree (carefully, not destructively), `Phase 1` codifies the contract in docs, then implementation phases for detection, recovery, UI surfacing, security review, QA, and CTO review.
+- Explicit assignees per phase; favor team specialty (CodexCoder for server, ClaudeCoder for FE, UXDesigner for visible state, SecurityEngineer for ownership/permissions, QA for validation).
+- Blocking dependencies wired with `blockedByIssueIds`, parallel branches identified.
+
+Do not create the child issues yet. Do not push code.
+
+### 6. Request approval, then decompose
+
+- Open a `request_confirmation` interaction targeting the latest plan revision. Idempotency key `confirmation:{issueId}:plan:{revisionId}`.
+- Wait for board/CTO acceptance. If the user posts a new comment that supersedes the plan, the prior confirmation is invalidated — open a fresh confirmation tied to the new revision ([PAP-2602](/PAP/issues/PAP-2602) cycled three revisions; that is fine).
+- Only after acceptance: create the phased child issues with the right assignees and dependencies, then block this parent on the final QA / CTO review issue so the parent only wakes when the chain finishes.
+
+### 7. Phase 0 hygiene on the named tree
+
+Phase 0 cleans up the live tree without papering over evidence:
+
+- Move stalled `in_review` leaves with no participant to `todo` with a precise next action and named owner ([PAP-2335](/PAP/issues/PAP-2335)).
+- Detach cancelled/dead blockers from chains they were holding hostage; do not silently mark issues `done` to clear backlog.
+- Leave a comment on the original named issue summarizing what changed and why; never hide the recovery chain history.
+
+### 8. Final close-out
+
+When the phase chain is complete, post a board-level summary comment on the parent issue: what changed, what the new contract is, what the rollout step is (e.g. "restart the control-plane to pick up the new response shape"), and the live state of the originally-named tree. Then close the parent.
+
+## Pitfalls
+
+- **Coding before approval.** The user has said "make a plan first" on every recent diagnostic issue. Producing code in the forensic phase wastes the round-trip.
+- **Restating one invariant at the cost of another.** Bound continuation too tightly and productive work stalls; loosen recovery and infinite loops return. Always check all three.
+- **Skipping the recent-work survey.** Proposing a contract that contradicts what shipped 24 hours ago is the easiest way to get the plan rejected.
+- **Letting "in_review" mean done.** A leaf assigned to another agent with no participant or active run is not progress; treat it as a stop.
+- **Bypassing company scoping.** Cross-company forensics needs a board-approved diagnostic path, not a database read.
+- **Recursive recovery.** Stranded-work recovery that recovers its own recovery issues is the canonical infinite loop ([PAP-2486](/PAP/issues/PAP-2486)). Detect it and refuse to deepen.
+- **Hiding the chain.** Don't silently delete or hide the symptomatic recovery issues — the operator needs the audit trail.
+
+## Verification checklist (before posting the plan)
+
+- [ ] The exact stop point in the named tree is identified with run ids / comment ids.
+- [ ] Recent shipped work in the same area was surveyed and is referenced.
+- [ ] Every non-progressing issue is classified human-needed / agent-actionable / already-covered.
+- [ ] The proposed rule is stated as a contract, not a patch.
+- [ ] All three invariants are explicitly preserved.
+- [ ] No code change has landed in this heartbeat.
+- [ ] A `request_confirmation` against the latest plan revision is open.
+- [ ] Phase 0 of the plan addresses the live named tree without destroying evidence.
+- [ ] Implementation phases name specialty-appropriate assignees and `blockedByIssueIds` dependencies.

package/skills/para-memory-files/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: para-memory-files
+description: >
+  File-based memory system using Tiago Forte's PARA method. Use this skill whenever
+  you need to store, retrieve, update, or organize knowledge across sessions. Covers
+  three memory layers: (1) Knowledge graph in PARA folders with atomic YAML facts,
+  (2) Daily notes as raw timeline, (3) Tacit knowledge about user patterns. Also
+  handles planning files, memory decay, weekly synthesis, and recall via qmd.
+  Trigger on any memory operation: saving facts, writing daily notes, creating
+  entities, running weekly synthesis, recalling past context, or managing plans.
+---
+
+# PARA Memory Files
+
+Persistent, file-based memory organized by Tiago Forte's PARA method. Three layers: a knowledge graph, daily notes, and tacit knowledge. All paths are relative to `$AGENT_HOME`.
+
+## Three Memory Layers
+
+### Layer 1: Knowledge Graph (`$AGENT_HOME/life/` -- PARA)
+
+Entity-based storage. Each entity gets a folder with two tiers:
+
+1. `summary.md` -- quick context, load first.
+2. `items.yaml` -- atomic facts, load on demand.
+
+```text
+$AGENT_HOME/life/
+  projects/          # Active work with clear goals/deadlines
+    <name>/
+      summary.md
+      items.yaml
+  areas/             # Ongoing responsibilities, no end date
+    people/<name>/
+    companies/<name>/
+  resources/         # Reference material, topics of interest
+    <topic>/
+  archives/          # Inactive items from the other three
+  index.md
+```
+
+**PARA rules:**
+
+- **Projects** -- active work with a goal or deadline. Move to archives when complete.
+- **Areas** -- ongoing (people, companies, responsibilities). No end date.
+- **Resources** -- reference material, topics of interest.
+- **Archives** -- inactive items from any category.
+
+**Fact rules:**
+
+- Save durable facts immediately to `items.yaml`.
+- Weekly: rewrite `summary.md` from active facts.
+- Never delete facts. Supersede instead (`status: superseded`, add `superseded_by`).
+- When an entity goes inactive, move its folder to `$AGENT_HOME/life/archives/`.
+
+**When to create an entity:**
+
+- Mentioned 3+ times, OR
+- Direct relationship to the user (family, coworker, partner, client), OR
+- Significant project or company in the user's life.
+- Otherwise, note it in daily notes.
+
+For the atomic fact YAML schema and memory decay rules, see [references/schemas.md](references/schemas.md).
+
+### Layer 2: Daily Notes (`$AGENT_HOME/memory/YYYY-MM-DD.md`)
+
+Raw timeline of events -- the "when" layer.
+
+- Write continuously during conversations.
+- Extract durable facts to Layer 1 during heartbeats.
+
+### Layer 3: Tacit Knowledge (`$AGENT_HOME/MEMORY.md`)
+
+How the user operates -- patterns, preferences, lessons learned.
+
+- Not facts about the world; facts about the user.
+- Update whenever you learn new operating patterns.
+
+## Write It Down -- No Mental Notes
+
+Memory does not survive session restarts. Files do.
+
+- Want to remember something -> WRITE IT TO A FILE.
+- "Remember this" -> update `$AGENT_HOME/memory/YYYY-MM-DD.md` or the relevant entity file.
+- Learn a lesson -> update AGENTS.md, TOOLS.md, or the relevant skill file.
+- Make a mistake -> document it so future-you does not repeat it.
+- On-disk text files are always better than holding it in temporary context.
+
+## Memory Recall -- Use qmd
+
+Use `qmd` rather than grepping files:
+
+```bash
+qmd query "what happened at Christmas"   # Semantic search with reranking
+qmd search "specific phrase"              # BM25 keyword search
+qmd vsearch "conceptual question"         # Pure vector similarity
+```
+
+Index your personal folder: `qmd index $AGENT_HOME`
+
+Vectors + BM25 + reranking finds things even when the wording differs.
+
+## Planning
+
+Keep plans in timestamped files in `plans/` at the project root (outside personal memory so other agents can access them). Use `qmd` to search plans. Plans go stale -- if a newer plan exists, do not confuse yourself with an older version. If you notice staleness, update the file to note what it is supersededBy.

package/skills/para-memory-files/references/schemas.md

@@ -0,0 +1,35 @@
+# Schemas and Memory Decay
+
+## Atomic Fact Schema (items.yaml)
+
+```yaml
+- id: entity-001
+  fact: "The actual fact"
+  category: relationship | milestone | status | preference
+  timestamp: "YYYY-MM-DD"
+  source: "YYYY-MM-DD"
+  status: active # active | superseded
+  superseded_by: null # e.g. entity-002
+  related_entities:
+    - companies/acme
+    - people/jeff
+  last_accessed: "YYYY-MM-DD"
+  access_count: 0
+```
+
+## Memory Decay
+
+Facts decay in retrieval priority over time so stale info does not crowd out recent context.
+
+**Access tracking:** When a fact is used in conversation, bump `access_count` and set `last_accessed` to today. During heartbeat extraction, scan the session for referenced entity facts and update their access metadata.
+
+**Recency tiers (for summary.md rewriting):**
+
+- **Hot** (accessed in last 7 days) -- include prominently in summary.md.
+- **Warm** (8-30 days ago) -- include at lower priority.
+- **Cold** (30+ days or never accessed) -- omit from summary.md. Still in items.yaml, retrievable on demand.
+- High `access_count` resists decay -- frequently used facts stay warm longer.
+
+**Weekly synthesis:** Sort by recency tier, then by access_count within tier. Cold facts drop out of the summary but remain in items.yaml. Accessing a cold fact reheats it.
+
+No deletion. Decay only affects retrieval priority via summary.md curation. The full record always lives in items.yaml.