@mndrk/agx 2.0.26 → 2.0.33

package/cloud-runtime/standalone/notes/comments-context-demo.md

@@ -1,141 +0,0 @@
-# Demo: Task Comments as Execution Context
-
-## What was built
-- Task comments are part of signed execution context.
-- `lib/task-context.ts` composes prompt context with a `COMMENTS` section and computes `comments_digest` (SHA-256 over ordered comments).
-- Signed payload producers re-compute digest and re-sign when comments change:
-  - `POST /api/tasks/[id]/comments`
-  - `DELETE /api/tasks/[id]/comments/[commentId]`
-  - `GET /api/tasks/[id]`
-  - `POST /api/queue` (pull)
-  - MCP `tasks.get` and `queue.pull`
-- Signature includes `comments_digest`, so stale signatures are invalid after comment mutations.
-
-## Acceptance status (2026-02-07)
-- E2E blocked in this sandbox by port restrictions (cannot bind localhost on `127.0.0.1:3100`).
-- Cloud sync blocked in this sandbox: `tsx` IPC socket bind blocked.
-- Rerun in an environment that allows localhost binds + IPC sockets and has DB credentials, then record results here.
-
-## Local setup (required for demo)
-1. Install dependencies:
-```bash
-npm install
-```
-2. Configure env:
-```bash
-cp .env.example .env.local
-# Fill in DB values for:
-# - NEXT_PUBLIC_DB_URL (or DB_URL)
-# - DB_SERVICE_ROLE_KEY
-```
-3. Run dev server:
-```bash
-npm run dev
-```
-Expected:
-- App available at `http://localhost:3000`.
-- Auth + task data load via DB.
-
-## Demo (UI)
-1. Start the app: `npm run dev`
-2. Open dashboard and select a task.
-3. Add a comment in `Comments`.
-4. Confirm it appears in timeline.
-5. Refresh and verify prompt/context now includes the comment.
-
-Expected:
-- `COMMENTS` section includes the new entry.
-- `comments_digest` changes after each comment mutation.
-- Returned `signature` matches the new digest.
-
-## Demo (API)
-1. Add comment:
-```bash
-curl -X POST "http://localhost:3000/api/tasks/<taskId>/comments" \
-  -H "Content-Type: application/json" \
-  -H "Authorization: Bearer <access_token>" \
-  -d '{"content":"Add context here"}'
-```
-2. Fetch task:
-```bash
-curl -X GET "http://localhost:3000/api/tasks/<taskId>" \
-  -H "Authorization: Bearer <access_token>"
-```
-3. Verify:
-- `comments_digest` present and updated.
-- `context.prompt` contains `COMMENTS`.
-- `signature` changes when digest changes.
-
-## Demo (Queue/MCP)
-1. Pull via queue (`POST /api/queue`) or MCP (`queue.pull`).
-2. Verify returned prompt includes `COMMENTS` and digest/signature fields.
-3. Add another comment and pull again; verify digest/signature roll forward.
-
-## E2E (Playwright) — rerun commands
-```bash
-npm run test:e2e:sandbox -- e2e/comments.spec.ts
-```
-If you are not in a sandbox and want to override host/port:
-```bash
-SANDBOX=1 CLOUD_SYNC_DISABLED=1 E2E_HOST=0.0.0.0 E2E_PORT=3101 npx playwright test e2e/comments.spec.ts
-```
-Expected:
-- Playwright starts Next.js dev server.
-- Browser flow creates a comment and validates digest/signature changes.
-
-## Cloud sync (MCP log) — rerun commands
-```bash
-export DB_URL="https://<project>.db.co"
-export DB_SERVICE_ROLE_KEY="<service-role-key>"
-node mcp/tmp-log.mjs
-```
-Expected:
-- MCP tool connects and writes a task log entry for this acceptance run.
-
-## Evidence (this environment)
-- `npm run test:e2e:sandbox -- e2e/comments.spec.ts` failed (Next.js web server did not start; no URL visited):
-  - Command output:
-    - `> agx-cloud@0.1.0 test:e2e:sandbox`
-    - `> SANDBOX=1 CLOUD_SYNC_DISABLED=1 E2E_HOST=127.0.0.1 E2E_PORT=3100 playwright test e2e/comments.spec.ts`
-    - `[WebServer] (node:11097) Warning: The 'NO_COLOR' env is ignored due to the 'FORCE_COLOR' env being set.`
-    - `[WebServer] (Use \`node --trace-warnings ...\` to show where the warning was created)`
-    - `[WebServer] ⚠ Warning: Next.js inferred your workspace root, but it may not be correct.`
-    - `[WebServer] We detected multiple lockfiles and selected the directory of /Users/mendrika/package-lock.json as the root directory.`
-    - `[WebServer] Detected additional lockfiles:`
-    - `[WebServer]   * /Users/mendrika/Projects/Agents/agx-cloud/package-lock.json`
-    - `[WebServer] (node:11098) Warning: The 'NO_COLOR' env is ignored due to the 'FORCE_COLOR' env being set.`
-    - `[WebServer] (Use \`node --trace-warnings ...\` to show where the warning was created)`
-    - `[WebServer] ⨯ Failed to start server`
-    - `[WebServer] Error: listen EPERM: operation not permitted 127.0.0.1:3100`
-    - `[WebServer] at <unknown> (Error: listen EPERM: operation not permitted 127.0.0.1:3100) {`
-    - `[WebServer]   code: 'EPERM'`
-    - `[WebServer]   errno: -1`
-    - `[WebServer]   syscall: 'listen'`
-    - `[WebServer]   address: '127.0.0.1'`
-    - `[WebServer]   port: 3100`
-    - `[WebServer] }`
-    - `Error: Process from config.webServer exited early.`
-- `DB_URL=https://iicvrgtzktvsrestfqif.db.co DB_SERVICE_ROLE_KEY="<service-role-key>" node mcp/tmp-log.mjs` failed (IPC socket blocked):
-  - Command output:
-    - `Error: listen EPERM: operation not permitted /tmp/tsx-501/11143.pipe`
-    - `at Server.setupListenHandle [as _listen2] (node:net:1918:21)`
-    - `at listenInCluster (node:net:1997:12)`
-    - `at Server.listen (node:net:2119:5)`
-    - `at file:///Users/mendrika/Projects/Agents/agx-cloud/mcp/node_modules/tsx/dist/cli.mjs:53:31537`
-    - `code: 'EPERM' errno: -1 syscall: 'listen' address: '/tmp/tsx-501/11143.pipe'`
-    - `Node.js v25.5.0`
-    - `Failed to log via MCP: McpError: MCP error -32000: Connection closed`
-    - `at McpError.fromError (file:///Users/mendrika/Projects/Agents/agx-cloud/mcp/node_modules/@modelcontextprotocol/sdk/dist/esm/types.js:2035:16)`
-    - `at Client._onclose (file:///Users/mendrika/Projects/Agents/agx-cloud/mcp/node_modules/@modelcontextprotocol/sdk/dist/esm/shared/protocol.js:259:32)`
-    - `at _transport.onclose (file:///Users/mendrika/Projects/Agents/agx-cloud/mcp/node_modules/@modelcontextprotocol/sdk/dist/esm/shared/protocol.js:223:18)`
-    - `at ChildProcess.<anonymous> (file:///Users/mendrika/Projects/Agents/agx-cloud/mcp/node_modules/@modelcontextprotocol/sdk/dist/esm/client/stdio.js:85:31)`
-    - `at ChildProcess.emit (node:events:508:20)`
-    - `at maybeClose (node:internal/child_process:1084:16)`
-    - `at ChildProcess._handle.onexit (node:internal/child_process:304:5) {`
-    - `code: -32000`
-    - `data: undefined`
-    - `}`
-
-## Notes
-- Comments beginning with `[execution/` or `Execution result from agx` are excluded from prompt context.
-- Clients should treat signature/digest mismatch as fatal and re-pull task context before continuing execution.

package/cloud-runtime/standalone/notes/comments-context-plan.md

@@ -1,119 +0,0 @@
-# Comments as execution context (ideation)
-
-## Goal
-- Ensure task comments become first-class context that cloud-signed tasks hand to agents, and document the scope for the implementation work.
-
-## Current state summary
-- A dedicated `task_comments` table exists, plus a React timeline (`LogTimeline`) and API routes (`/api/tasks/[id]/comments`) to fetch/add comments.
-- `lib/task-context.ts` builds a prompt that already includes `COMMENTS` and computes a `comments_digest` that is injected into the signed payload in `/api/queue`.
-- The digest is covered by the HMAC implementation (`signTask`/`verifyTaskSignature`), and unit tests already assert digest changes affect the signature.
-
-## Identified gaps
-1. The MCP server (cloud API used by CLI/aggregator) still only returns task frontmatter; it neither fetches comment rows nor re-signs with digest, so CLI/agents pulling via MCP lose the context and security binding.
-2. Daemon/CLI workflows currently depend on db-reachable APIs; adding comment context requires confirming the aggregator pulls the new prompt/`comments_digest` instead of reusing stale signatures.
-3. There is no documented procedure for ensuring user comments trigger a new signed context before the daemon executes (the queue route handles it, but we should double-check aggregator flows). 
-
-## Progress since last review
-- `queue/pull` already builds and signs the full task context (prompt + `comments_digest`) when marking tasks as in_progress.
-- `tasks/get` now uses `buildTaskContext`, so MCP clients retrieving a task receive the same comment/learning context and digest that the queue path returns.
-- Added regression coverage for `/api/tasks/[id]` GET that mocks `buildTaskContext` and asserts the comments/`comments_digest` payload is merged before returning the task, ensuring the API surface matches what daemons receive.
-
-## Research takeaways (this turn)
-- `queue/pull` calls `buildTaskContext`, so each pull loads the latest comments/learnings/stage prompt, recomputes `comments_digest`, and re-signs (and persists) the task signature whenever the digest changes, keeping the daemon-bound payload consistent with on-disk comments.
-- `/api/queue` already has regression coverage showing that updating the digest triggers a new HMAC signature and persistence, which means any CLI/aggregator hitting that endpoint will automatically receive the refreshed signature once comments mutate.
-- `tasks/get` invokes `buildTaskContext` and merges the resulting prompt/digest into the API response, so MCP clients that re-fetch a task while waiting for work receive the same signed context the daemon executes with.
-- The same `buildTaskContext` helper is shared by `queue/pull` and `tasks/get`, ensuring future changes to comment rendering or digest computation stay in sync across daemon queue pulls and CLI/task fetches.
-
-
-## Updated approach
-1. Keep MCP queue pulls responsible for signing the comment-bound digest and persisting the new signature whenever the digest changes.
-2. Mirror the same context-building logic in MCP `tasks/get` so any client fetching a task still sees the digest and prompt the daemon will execute with.
-3. Document the expectations for comments as signed context, including how clients should handle new/edited comments (re-fetch, re-validate signature) and what happens if a comment arrives while the daemon is running.
-4. Surface tests (or test ideas) that exercise adding a comment, recomputing the digest, and ensuring the queued signature updates so we can catch regressions.
-
-## Signed comment expectations (cloud context)
-
-- `buildTaskContext` already concatenates the comments timeline, the current stage prompt, and required learnings before returning `comments_digest`. Any cloud-signed payload (`/api/queue`, `queue/pull`, etc.) must go through this helper so the daemon sees the most recent instructions.
-- When a user posts a comment through `/api/tasks/[id]/comments`, the route re-runs `buildTaskContext`, extracts the refreshed `comments_digest`, and re-signs the task before persisting it (see the `signTask` call inside the POST handler). That ensures the stored signature always reflects the comment set that will drive execution.
-- Clients that mutate comments—whether via the web UI or the MCP `tasks/log`/`tasks/comments` tools—should immediately re-fetch `/api/tasks/[id]` or the MCP `tasks/get` result to pull the rebuilt prompt, the new `comments_digest`, and the updated signature. If the signed payload differs from what the daemon previously received, treat it as a signal to halt the running work and pull again once the new context is verified.
-- Aggregators and daemons must continue to verify signatures on every queue pull. Because the signature covers `comments_digest`, replaying a cached signature after a comment change should surface as a verification failure, preventing execution with an outdated instruction set.
-- Operators should expect that comments can arrive mid-run; the safest workflow is to re-verify or re-pull whenever a comment mutation is observed, and to rely on the queue path’s automatic re-signing to keep the daemon-bound payload consistent.
-
-## Example request/response flows
-
-1. **Comment addition:**
-   - **Request:** `POST /api/tasks/123/comments` with body `{
-       "body": "Agent, please prioritize the new issue.",
-       "user_id": "user-abc"
-     }`.
-   - **Actions:** handler inserts the comment, calls `buildTaskContext(task)`, picks up the new `COMMENTS` section and digest, then signs the refreshed payload (including `comments_digest`) before updating `tasks.signature`.
-   - **Response:** `{
-       "id": 123,
-       "comments_digest": "sha256-xyz",
-       "signature": "hmac-abc",
-       "context": {
-         "prompt": "...COMMENTS...",
-         "comments": [...]
-       }
-     }` (clients should treat `signature`/`comments_digest` as the new ground truth and discard any cached payload tied to the previous digest).
-
-2. **Daemon queue pull:**
-   - **Request:** `POST /api/queue/pull` with daemon credentials and the task ID it is about to execute.
-   - **Actions:** queue route rebuilds the task context, recomputes `comments_digest`, and, if the digest differs from the stored value, re-signs and persists the task. The endpoint returns the signed payload so the daemon runs the latest prompt+comments.
-   - **Response:** same structure as the stored task but with the current `comments_digest` and `signature`. The daemon must verify the signature before executing and, if verification fails, abort and re-pull.
-
-3. **MCP task fetch:**
-   - **Request:** `GET /mcp/tasks/get?task_id=123` (or the equivalent CLI `tasks/get`).
-   - **Actions:** MCP `tasks.get` calls `buildTaskContext`, merges the `comments_digest` and prompt into the payload, and re-signs if necessary before returning.
-   - **Response:** `{
-       "task": {...},
-       "comments_digest": "sha256-xyz",
-       "signature": "hmac-abc",
-       "context": {...}
-     }`.
-
-## Failure handling & verification guidance
-
-- Clients (daemons, aggregators, or operators) that observe a comment mutation must treat signature/digest mismatches as fatal: do not proceed with the previously cached execution context. Instead, trigger a refresh (`/api/tasks/[id]` or `/api/queue/pull`) and verify the returned `signature` over the new `comments_digest` before continuing.
-- If signature verification fails even after re-fetching the task, assume the comment context may have been tampered with or left partially applied; log the failure, halt further execution, and surface the issue through the operator webhook/log stream so the issue can be investigated before retrying.
-- The queue pull endpoint already recomputes the digest, but daemons should still verify the signature locally to detect any corruption between the cloud response and their cached copy.
-- For MCP consumers that write comments via CLI tooling, ensure those commands re-fetch the signed task afterward so the digest and signature accompanying follow-on work are consistent; do not rely on eventual re-pulls alone since a new comment might be the trigger for higher-priority instructions.
-
-## Regression test checklist
-
-1. **`/api/tasks/[id]/comments` POST:**
-   - Mock `buildTaskContext` to return a digest that changes after the comment is inserted.
-   - Assert the route re-signs the task, persists the new `signature`, and includes the updated `comments_digest` in the response.
-   - Verify downstream handlers (e.g., task fetch) are supplied with the new digest as soon as the route completes.
-
-2. **`/api/queue/pull`:**
-   - Seed a task with an existing `comments_digest`/`signature`, then insert a comment that changes the digest.
-   - Confirm `queue/pull` recomputes the digest, re-signs the task, stores the new signature, and returns the refreshed `comments_digest` to the daemon.
-   - Ensure the daemon-side signature verification helper fails when presented with the old digest/signature pair (so we catch regressions where verification is skipped).
-
-3. **MCP `tasks/get` (cloud API):**
-   - Stub `buildTaskContext` to return different digests before and after a comment mutation.
-   - Assert the MCP helper merges the new `comments_digest` into the response and re-signs the payload before returning.
-   - Add an end-to-end test that simulates the CLI fetching a task after posting a comment and verifies the signature verification step accepts the new digest and rejects the old one.
-
-4. **Tooling/verification notes:**
-   - Tests need low-level access to `signTask`/`verifyTaskSignature` to assert a digest change truly rotates the signature; stubbed helpers should mirror the production logic, otherwise we risk false positives.
-   - Logging or metric hooks should capture signature verification failures so we can detect clients that skip the re-fetch cycle; add assertions in tests that the failure path is exercised when mismatched signatures appear.
-
-## Effort estimate
-- MCP server enhancement (prompt generation + digest handling): 1.5–2 days
-- Tests/documentation + stash/hand-off notes: 0.5 day
-- Total: ~2–2.5 working days (assuming no additional infra blockers).
-
-## Unknowns / questions
-- Does the CLI/aggregator currently read the MCP `task.signature` and verify it before execution, or will we need to update it to replay the new digest?
-- Are there any other sources of editable context (e.g., learnings or logs) that also need digesting in the same signed payload?
-- What user_id should new comments/learnings be attached to when we insert/update them via MCP (the cloud API)?
-- Are there rate limits or permission guardrails that will prevent us from re-signing tasks with new digests on every pull?
-- Should there be an explicit signal (webhook, SSE, etc.) to the daemon/aggregator when comments change so we can safely abort the current execution and re-pull the refreshed signature?
-- Do comment edits (not just additions) automatically move through the same digest/resign flow, or do we need an extra hook for edit operations?
-
-## Next concrete steps
-1. (Done) Expanded regression coverage by adding a MCP queue/pull test that ensures `comments_digest` changes trigger re-signing and persistence in the MCP workflow.
-2. (Done) Document the signed-comment expectations for clients/operators, covering the re-fetch workflow, required validation steps, and how daemons should behave when a comment arrives while running.
-3. Validate aggregator/daemon signature verification flow end-to-end and capture any outstanding requirements before moving to planning/coding.

package/cloud-runtime/standalone/notes/context-audit.md

@@ -1,21 +0,0 @@
-# Context handling audit
-
-## agx-cloud
-
-- `lib/task-context.ts` builds the signed execution context sent to agents. It gathers comments for a task, fetches learnings scoped to the task/project/global buckets, resolves the stage prompt from `stage_prompts`, and then renders a multi-section prompt (`STAGE PROMPT`, `TASK META`, `COMMENTS`, `LEARNINGS (task|project|global)`). The resulting `TaskContext` (prompt + `comments_digest`) is spread into the responses from `/api/tasks`, `/api/queue`, and several MCP helpers so daemons/agx cli receive all the metadata they need before executing a stage.
-- The current schema only stores a loose `project` string per task; there is no structured project record or repo metadata backing `project_context`, so anything beyond the simple label is runtime-only and held in notes (see `notes/project-layer.md`).
-- APIs such as `app/api/tasks/route.ts`, `/api/tasks/[id]/comments`, and the MCP CLI (`mcp/src/tools/*.ts`) all call `buildTaskContext`, meaning the pipeline already supports injecting richer context if we extend the helper.
-
-## agx CLI
-
-- `lib/executor.js` builds stage prompts entirely on the CLI side. It reads a stage name from the task metadata, looks up `STAGE_CONFIG` to retrieve the hard-coded instructions (e.g., "Create detailed plan with tasks, milestones, and dependencies" for planning), and then emits a `buildPrompt` that wraps the static prompt, the full task content, and a fixed instruction list (`[checkpoint]`, etc.). No cloud-provided context or learnings are merged in.
-- Tasks created with `agx new` collect frontmatter that includes the `project` string (`index.js` around lines 2976-3025), but the CLI only ships that text as part of the task payload; it does not know anything about repo paths, CI/CD hints, or aggregated learnings tied to a project entity.
-- Helper scripts like `lib/worker.js` and `lib/realtime.js` print the raw `project` label when reporting progress, but they never refer to a richer project object or project-specific metadata.
-
-## Gaps to close for the new project layer
-
-1. The CLI has no way to request or receive structured `project_context` data (repo mapping, CI/CD notes, stack learnings) when invoking a task; it simply reruns the stale frontmatter/stage prompt mix that predates the planned feature.
-2. The cloud already centralizes comments, stage prompts, and learnings via `buildTaskContext`, so extending that helper to add project metadata would give every downstream caller the enriched view we need, but the current schema/API surface lacks a `projects` entity to base that metadata on.
-3. We must define how a project is stored (schema/migrations), how tasks learn of their parent project (FK, slug, etc.), and how the CLI/daemon request it when building prompts.
-
-Next action: finish this audit by matching whichever `lib/db` helpers and DB migrations will need updates so we can define the new `projects` and `project_repos` tables with the right FK relationships.

package/cloud-runtime/standalone/notes/project-layer-plan.md

@@ -1,30 +0,0 @@
-# Project layer plan for agx-cloud agx-agent flow
-
-## Summary
-- Capture how the CLI/daemon should obtain and surface structured project metadata, repo mapping, CI/CD hints, and learnings so that agents execute with a consistent context from idea through release.
-- Define the data model, API surfaces, and prompt pipeline changes needed to treat projects as first-class entities shared between agx-cloud, agx CLI, and MCP/daemon workloads.
-
-## Task breakdown
-| ID | Task | Details | Dependencies | Owner | Effort |
-| --- | --- | --- | --- | --- | --- |
-| T1 | Schema & FK design | Define `projects` + `project_repos`, link `tasks`/`learnings` to `project_id`, and sketch migrations + RLS updates. | None | Backend | 2d |
-| T2 | Project APIs & MCP enrichment | Add CRUD endpoints, ensure `/api/tasks` + `/api/queue` embed `project_context`, and extend MCP helpers (`tasks.get`, `queue.pull`) and `buildTaskContext`. | T1 | Backend | 2d |
-| T3 | CLI/daemon prompt flow | Pass `project_context` through `agx run/new` + `lib/executor.js`, render `PROJECT CONTEXT` + `REPO MAP`, and make learnings resolve project-scoped history. | T2 | CLI | 1d |
-| T4 | Cloud UI surfaces | Add project management views/forms, show context/CI status in dashboard/task detail, and link learnings to projects. | T2 | Frontend | 1.5d |
-| T5 | Testing & documentation | Update regression tests (task context, MCP) and document how project context flows; detail how CLI/UI should refresh when project metadata changes. | T2, T3, T4 | Full stack | 1d |
-
-## Milestones
-1. **Foundation (Deadline TBD)** – Schema/migration + API surfaces exist, ensuring `project_context` can be signed and delivered to any task consumer. 
-2. **Context surfaces** – CLI/daemon prompts and cloud UI display the enriched project metadata so agents have repo mappings, CI/CD info, and learnings. 
-3. **Rollout + coverage** – Tests/docs updated, learnings pipeline scoped to projects, and rollout notes outline how to migrate existing tasks.
-
-## Dependencies
-- Schema migration must precede any backend or CLI work that references `projects`/`project_repos` columns.
-- MCP helpers and `buildTaskContext` need the final project payload before CLI/daemon prompt changes are merged.
-- Frontend components use the new APIs, so backend endpoints must be ready before the UI surfaces can be wired.
-- Learnings pipeline relies on a stable project identifier; ensure `scope_id` updates once the project row exists.
-
-## Next concrete steps
-1. Solidify the migration SQL and update `lib/db` helpers/policies to expose `projects` + `project_repos` with the necessary joins.
-2. Extend `buildTaskContext` and the MCP helpers to include the new `project_context` section so every agent sees the metadata.
-3. Note that cloud API sync (writing to DB) will validate once the schema and MCP endpoints are running; record the plan via the MCP task log or equivalent once the server is accessible.

package/cloud-runtime/standalone/notes/project-layer.md

@@ -1,123 +0,0 @@
-# Project layer planning for agx cloud + CLI
-
-## Background
-- The control plane currently stores a loose `project` string per task (see `db/migrations/001_initial_schema.sql`); agents and learnings already reference this slot but there is no structured project definition or repo metadata.
-- Learnings are scoped to `task`, `project`, or `global` and are pulled into prompts through `lib/task-context.ts` to avoid repetition, but the CLI still builds prompts solely from task frontmatter defined in `lib/executor.js`, so neither side has a consistent picture of project context.
-
-## Requirements
-1. Define a first-class `projects` entity (name, description, owner, metadata, CI/CD pointers) and a `project_repos` child table that records repo names/paths/notes for the project.<br>
-2. Surface project metadata via new APIs so agx-cloud can show/manage projects and the daemon/CLI can fetch rich context along with tasks.
-3. Ensure learnings/comments scoped to the project use the project identifier produced by the new entity so agents can reuse insights.
-4. Update the CLI/daemon prompt pipeline to receive `project_context` (stack notes, repo mapping, CI/CD state) and append a `PROJECT CONTEXT` section before executing.
-5. Provide UI affordances (dashboard, task detail, new project management view) so users can define the project only once and review it when executing tasks.
-6. Keep security/integrity boundaries intact: project metadata must be stored per user/organization and only exposed to that user's agents.
-
-## Implementation approach
-1. **Backend schema & API**
-   - Create `projects` table (`id`, `user_id`, `name`, `slug`, `description`, `metadata JSON`, `ci_cd_info text`, `created_at`, `updated_at`).
-   - Add `project_repos` table (`id`, `project_id`, `name`, `path`, `git_url`, `notes`).
-   - Link tasks to projects via `project_id` or slug and update `learnings.scope_id` references accordingly.
-   - Build REST endpoints (`GET /api/projects`, `POST /api/projects`, `GET/PUT/DELETE /api/projects/:id`, `POST /api/projects/:id/repos`, etc.).
-   - Embed project context when returning a task from `/api/tasks` and `/api/queue`, extending `buildTaskContext` to include `project_context` (stack, repos, ci/cd) alongside stage prompts.
-2. **Cloud UI**
-   - Add a project management funnel (new page or modal) that lets users register project name, description, main branches, CI/CD endpoints, and repo list with notes.
-   - Show project link/summary inside the dashboard/task detail and reuse `project_context` data when users inspect learnings or comments.
-3. **CLI/Daemon**
-   - When `agx run` or daemon fetches a task, read the extended task payload that now contains `project_context` alongside `content` and `stage_config`.
-   - Update `runSingleAgentIteration`/`buildPrompt` (inside `lib/executor.js`) to include a new `PROJECT CONTEXT` section describing repo locations and CI/CD hints, and maybe a `PROJECT NOTES` bullet list.
-   - Allow `agx new` to either accept `--project-id` or `--project` slug so tasks can be created within a registered project (and fallback to legacy text fields).
-4. **Learnings integration**
-   - Ensure UI and CLI know how to attach learnings to the new project identifier so `LEARNINGS (project)` continues to show relevant entries even if the project now has structured metadata.
-   - Consider automating project insights ingestion (e.g., propagate `project_context` to `PROJECT CONTEXT` sections the same way comments are included).
-
-## Effort estimate
-- Backend schema + API plus DB policies: 2–3 days (one day to design schema + migrations, another to wire API + RLS + tests).
-- Front-end project management surface (dashboard, modals, listing): 1.5–2 days (UI/UX + data fetching + linking to learnings).
-- CLI/daemon prompt changes, `agx new` flags, and aggregator updates: 1–1.5 days (prompt composition + ensure stage config merges new context).
-- Integration/testing (end-to-end flows, verifying learnings + prompt sections, documentation): 0.5–1 day.
-- **Total:** ~5–7 days of focused work depending on iterations.
-
-## Unknowns
-- Should tasks reference `projects` by slug/name or by `project_id`? This affects backward compatibility for existing tasks with free-text `project` values.
-- Does the project context need to reference actual local repo paths (for CLI) or purely remote repository metadata (URL/branch) that agents can reason about?
-- Do multiple users share projects/learnings or is everything per-user? We need to confirm sharing expectations to enforce RLS scopes on new tables.
-- How granular should CI/CD context be (just tooling names, or actual URLs/credentials)? Need to balance fidelity with not storing secrets.
-- Should `project_context` be editable alongside projects (versioning?). Agents will rely on it, so we need to decide whether to provide history or just the latest snapshot.
-
-## Detailed plan
-
-### Task roadmap
-
-| Task | Description | Dependencies | Milestone | Effort |
-| --- | --- | --- | --- | --- |
-| Schema + migrations | Create `projects` + `project_repos`, add RLS/policies, link tasks/learnings to the new entity, and expose slug/metadata columns used by `project_context`. | None (foundation) | Milestone 1 | 2–3 days |
-| API & MCP payloads | Extend DB APIs, `buildTaskContext`, `/api/tasks`, `/api/queue`, and MCP helpers so every task response embeds `project_context` (stack notes, repos, CI/CD info). | Schema + migrations | Milestone 1 → 2 | 2 days |
-| Cloud project surface | Add dedicated project CRUD UI (dashboard/modal), allow entering repo metadata, CI/CD hints, and surface the context inside task/detail panels. | API & MCP payloads | Milestone 2 | 1.5–2 days |
-| CLI/daemon integration | Let `agx new/run` accept project slugs/IDs, pull the enriched task payload, and append a `PROJECT CONTEXT` section before executing stage prompts. | API & MCP payloads | Milestone 2 | 1–1.5 days |
-| Learnings & docs | Ensure project-scoped learnings persist the new identifier, document how context flows, and add regression tests for the signature/prompt path. | CLI/daemon integration | Milestone 3 | 1 day |
-
-### Milestones
-
-- **Milestone 1 (Foundation):** Schema + API work complete, including migrations, DB policies, and new `/projects` endpoints. Tasks can now persist structured project metadata and serve it via `buildTaskContext`. (~2–3 days)
-- **Milestone 2 (Context surfaces):** Cloud UI and CLI/daemon consume the enriched data so agents receive repo mapping, stack notes, and CI/CD info in their prompts. (~2–3 days)
-- **Milestone 3 (Hardening):** Learnings, documentation, and regression tests updated to reflect the new flow; rollout notes captured for operators. (~1 day)
-
-### Dependencies
-
-- API surface cannot ship before the schema exists and is tested; migrations must be committed before any handler references the new tables.
-- Cloud UI depends on new APIs/project payloads to render repo/CI context, so backend work must precede the frontend.
-- CLI/daemon prompts require the enriched payloads plus learnings so `PROJECT CONTEXT` stays consistent with what the cloud UI shows.
-- Regression tests/documentation depend on at least one end-to-end flow locking in the new context data.
-
-### Next steps
-
-- (Now) Review the draft migration and ensure `lib/db` helpers and DB policies match the new `projects/project_repos` schema before exposing it via `project_context`.
-- After verifying the schema, update `lib/task-context.ts`/`mcp` helpers to inject project metadata into the signed payload, ensuring CLI/daemon clients receive it.
-
-## Milestone 2 detail
-
-### Schema shape
-- `projects` (`id uuid pk default gen_random_uuid()`, `user_id uuid references auth.users`, `name text`, `slug text unique`, `description text`, `metadata jsonb default '{}'`, `ci_cd_info text`, `project_learnings text[]`, `created_at timestamptz default now()`, `updated_at timestamptz default now()`). `metadata` stores stack decisions (framework, infra, runtime) and any arbitrary key/values the agents need in prompts.
-- `project_repos` (`id uuid pk`, `project_id uuid references projects(id) on delete cascade`, `name text`, `path text`, `git_url text`, `notes text`, `created_at timestamptz default now()`). `path` is the local repo path the CLI can mount, while `git_url` is used for context when the agent reviews remote sources.
-- `tasks` gains `project_id uuid references projects(id)` and retains the existing `project text` for backwards compatibility (copy legacy values into `projects.slug` on migration). `learnings` retains `scope` + `scope_id`, and when the scope is `project` the `scope_id` should reference `projects.id`.
-
-Example SQL snippet for migrations:
-```sql
-create table projects (
-  id uuid primary key default gen_random_uuid(),
-  user_id uuid references auth.users on delete cascade,
-  name text not null,
-  slug text unique not null,
-  description text,
-  metadata jsonb default '{}' not null,
-  ci_cd_info text,
-  project_learnings text[] default '{}',
-  created_at timestamptz default now(),
-  updated_at timestamptz default now()
-);
-
-create table project_repos (
-  id uuid primary key default gen_random_uuid(),
-  project_id uuid references projects(id) on delete cascade,
-  name text not null,
-  path text,
-  git_url text,
-  notes text,
-  created_at timestamptz default now()
-);
-```
-
-### API contract
-- `GET /api/projects`: returns `[ { id, slug, name, description, metadata, ci_cd_info, repos: [{ name, path, git_url, notes }] } ]`. Should respect RLS on `user_id`.
-- `POST /api/projects`: accepts `{ name, slug, description?, metadata?, ci_cd_info?, repos?: [ { name, path, git_url, notes } ] }` and creates `projects` + `project_repos`. Returns created project payload.
-- `GET /api/projects/:id`: returns single project with repo list and summary of `project_learnings`.
-- `PUT /api/projects/:id`: updates metadata/ci info and upserts repo entries, keyed by repo `name`.
-- `/api/tasks` and `/api/queue` responses embed `project_context` as `{ project: { id, name, slug, description, ci_cd_info, metadata }, repos: [ { name, path, git_url, notes } ], learnings: project_learnings }` alongside existing stage data.
-- When tasks are created via `POST /api/tasks`, allow `project_id` or `project_slug` to associate them with a registered project.
-
-### CLI/agent context consumption
-- The CLI should expect `project_context` inside the task payload and append the following sections to every stage prompt:
-  - `PROJECT CONTEXT` block describing `project.name`, `project.description`, and key entries from `ci_cd_info`/`metadata`.
-  - `REPOSITORY MAP` listing each repo's `name`, `path`, and `git_url` plus any `notes`. This gives the agent a quick reference to local repo paths and relevant remarks.
-  - `LEARNINGS` bullet list derived from `project_context.learnings`, to avoid repeating previously recorded issues.
-- When the daemon persists new learnings with a `scope: project`, it should attach `scope_id: project.id` so cloud learnings queries display the structured project history.

package/cloud-runtime/standalone/notes/temporal-migration-design.md

@@ -1,199 +0,0 @@
-# AGX Cloud Temporal Migration Design
-
-## Status
-- Author: Codex
-- Date: 2026-02-07
-- Scope: Replace custom queue/claim/heartbeat orchestration with Temporal workflows while preserving existing AGX task APIs and security model.
-
-## Context
-`agx-cloud` now orchestrates multi-stage tasks through Temporal workflows and HTTP control endpoints:
-- Queue pull: `GET /api/queue`
-- Heartbeat: `POST /api/tasks/:id/heartbeat`
-- Stage completion: `POST /api/queue/complete`
-
-This works, and Temporal now covers reliability requirements (durable execution, retries, and workflow history).
-
-## Goals
-1. Durable multi-stage execution with restart-safe state.
-2. Remove custom lease/heartbeat semantics from critical path.
-3. Keep existing AGX task model (`ideation -> planning -> coding -> qa -> acceptance -> pr -> pr_review -> merge -> done`).
-4. Preserve existing security requirements: signed task payloads, audit logging, user isolation.
-5. Minimize disruption for existing CLI/daemon users.
-
-## Non-Goals
-- Replacing DB/Postgres for product data.
-- Rewriting the UI task model.
-- Migrating historical task rows to new schema immediately.
-
-## Proposed Architecture
-
-### Core model
-- One **Temporal Workflow Execution per task**.
-- Workflow ID: `task:<taskId>`.
-- Temporal task queue: `agx-task-workers`.
-- Namespace: `agx`.
-
-### Workflow shape
-- Workflow function: `taskWorkflow(input)`.
-- Each SDLC stage is one deterministic workflow step.
-- Each stage invokes an Activity to request execution from daemon/agent path.
-- Stage result drives transition (`done`, `blocked`, `not_done`, `failed`).
-
-### Activities
-- `dispatchStageActivity(taskId, stage, config)`
-- `recordStageDecisionActivity(taskId, decision)`
-- `advanceStageActivity(taskId, nextStage)`
-- `markBlockedActivity(taskId, reason)`
-- `markFailedActivity(taskId, reason)`
-- `appendTaskLogActivity(taskId, log)`
-- `appendTaskCommentActivity(taskId, comment)`
-
-Activities can call existing DB helpers and APIs. Workflow code remains deterministic.
-
-### Signals and queries
-- Signals:
-  - `agentResult(decisionPayload)`
-  - `cancelTask(reason)`
-  - `humanInput(commentPayload)`
-- Queries:
-  - `getStatus()` returns stage, decision, retries, last update.
-
-## Stage State Machine
-- Ordered path for `task` tickets:
-  `ideation -> planning -> coding -> qa -> acceptance -> pr -> pr_review -> merge -> done`
-- `spike` ticket behavior:
-  `ideation -> planning -> done`
-- Decision handling:
-  - `done`: advance stage
-  - `blocked`: set task blocked, wait for signal/manual intervention
-  - `not_done`: retry same stage with policy
-  - `failed`: retry until max attempts, then fail task
-
-## Reliability Model
-Temporal replaces:
-- custom worker ownership leases
-- custom heartbeat refresh
-- stale lease scavenging
-
-Use Temporal features:
-- Activity heartbeat + timeout
-- retry policy (exponential backoff)
-- workflow history for crash recovery
-- idempotent Workflow ID to avoid duplicate executions
-
-## API Compatibility Plan
-Maintain existing API contracts for clients while changing backend implementation.
-
-### Compatibility mapping
-- `GET /api/queue`:
-  - Short term: unchanged for legacy workers.
-  - New mode: returns Temporal-assigned work or no-op if workflow already active.
-- `POST /api/tasks/:id/heartbeat`:
-  - Legacy compatibility only; eventually deprecated.
-- `POST /api/queue/complete`:
-  - In Temporal mode, transformed into `agentResult` signal to task workflow.
-
-### New internal endpoints (service-to-service)
-- `POST /internal/workflows/tasks/:taskId/start`
-- `POST /internal/workflows/tasks/:taskId/signal`
-- `POST /internal/workflows/tasks/:taskId/cancel`
-- `GET /internal/workflows/tasks/:taskId/status`
-
-## Data Model Changes
-Add to `tasks` table:
-- `orchestrator` text default `legacy` (`legacy` | `temporal`)
-- `workflow_id` text null
-- `workflow_run_id` text null
-- `orchestration_status` text null
-- `last_orchestration_update` timestamptz null
-
-Add optional table `task_workflow_events`:
-- immutable mirror of key workflow events for product analytics and support.
-
-No immediate destructive schema changes.
-
-## Worker Topology
-
-### Services
-1. `agx-cloud` (Next.js API + UI)
-2. `temporal` server
-3. `temporal-ui`
-4. `temporal-admin-tools`
-5. `temporal-postgres` (Temporal persistence)
-6. `agx-temporal-worker` (Node worker process in `agx-cloud` repo)
-
-### Separation of concerns
-- Next.js app starts workflows and writes user-facing state.
-- Temporal worker executes Activities and handles retries/timeouts.
-- Daemon/agent execution path remains external and communicates results via API/signal.
-
-## Security Considerations
-- Keep task-signing verification in Activity boundary before any execution dispatch.
-- Authenticate internal workflow control endpoints with service token.
-- Enforce tenant scoping by user ID in every Activity DB query.
-- Log every workflow transition into existing `task_audit_log`.
-
-## Migration Strategy
-
-### Phase 0: Foundation
-- Add Temporal infrastructure and worker skeleton.
-- Add feature flag: `ORCHESTRATOR_MODE=legacy|shadow|temporal`.
-
-### Phase 1: Shadow mode
-- Continue legacy orchestration as source of truth.
-- Start Temporal workflows in parallel (no writes that change task outcome).
-- Compare state transitions and decisions for drift.
-
-### Phase 2: Controlled cutover
-- Enable Temporal for a small cohort (internal users or selected projects).
-- Keep legacy endpoints as compatibility facade.
-
-### Phase 3: Full cutover
-- Default new tasks to `orchestrator=temporal`.
-- Keep fallback path for rollback.
-
-### Phase 4: Decommission legacy
-- Remove heartbeat hot path once stable.
-- Keep read-only compatibility behavior for a transition period.
-
-## Rollback Plan
-- Flip `ORCHESTRATOR_MODE=legacy`.
-- New tasks route to legacy queue immediately.
-- In-flight Temporal workflows are paused/cancelled and task status reconciled by script.
-
-## Testing Plan
-1. Unit tests for workflow transition logic (all decisions and stage edge cases).
-2. Activity tests with mocked DB and daemon APIs.
-3. Integration tests with Temporal test server covering:
-   - worker restart mid-stage
-   - activity timeout and retry
-   - blocked/unblocked via signal
-   - cancellation
-4. Soak test with concurrent workflows and forced failures.
-
-## Observability
-- Correlation IDs: `task_id`, `workflow_id`, `run_id` in all logs.
-- Metrics:
-  - stage duration
-  - activity retry count
-  - workflow failure rate
-  - blocked-time duration
-- Temporal UI on `http://localhost:8088` for local debugging.
-
-## Open Decisions
-1. Whether daemon remains pull-based (`/api/queue`) or moves to push/signal driven callbacks first.
-2. Exact max retry policy per stage (uniform vs stage-specific).
-3. Whether to model each stage as a child workflow (stronger isolation) or single workflow loop (simpler).
-
-## Local Development Bootstrap
-Use the main compose file:
-
-```bash
-cd /Users/mendrika/Projects/Agents/agx-cloud
-docker compose up -d
-```
-
-Expected local endpoints:
-- Temporal gRPC: `localhost:7233`
-- Temporal UI: `http://localhost:8088`
-- Temporal Postgres: `localhost:5433`