chore(docs): update roadmap and design

Author: krokoko

cdk/src/handlers/shared/context-hydration.ts

@@ -793,12 +793,12 @@ export interface HydrateContextOptions {
 
 /**
  * Hydrate context for a task: resolve GitHub token, fetch issue/PR, enforce
- * token budget, assemble the user prompt, and (for PR tasks) screen through
- * Bedrock Guardrail for prompt injection.
+ * token budget, assemble the user prompt, and screen through Bedrock Guardrail
+ * for prompt injection (PR tasks; new_task when issue content is present).
  * @param task - the task record from DynamoDB.
  * @param options - optional per-repo overrides.
- * @returns the hydrated context. For PR tasks, `guardrail_blocked` is set when
- *          the guardrail intervened.
+ * @returns the hydrated context. `guardrail_blocked` is set when the guardrail
+ *          intervened (PR tasks: always screened; new_task: screened when issue content is present).
  * @throws GuardrailScreeningError when the Bedrock Guardrail API call fails
  *         (fail-closed — propagated to prevent unscreened content from reaching the agent).
  */
@@ -990,13 +990,19 @@ export async function hydrateContext(task: TaskRecord, options?: HydrateContextO
       return prContext;
     }
 
-    // Standard task: existing behavior
+    // Standard task
     const budgetResult = enforceTokenBudget(issue, task.task_description, USER_PROMPT_TOKEN_BUDGET);
     issue = budgetResult.issue;
 
     userPrompt = assembleUserPrompt(task.task_id, task.repo, issue, budgetResult.taskDescription);
     const tokenEstimate = estimateTokens(userPrompt);
 
+    // Screen assembled prompt when it includes GitHub issue content (attacker-controlled input).
+    // Skipped when no issue is present — task_description is already screened at submission time.
+    const guardrailAction = issue
+      ? await screenWithGuardrail(userPrompt, task.task_id)
+      : undefined;
+
     return {
       version: 1,
       user_prompt: userPrompt,
@@ -1005,6 +1011,9 @@ export async function hydrateContext(task: TaskRecord, options?: HydrateContextO
       sources,
       token_estimate: tokenEstimate,
       truncated: budgetResult.truncated,
+      ...(guardrailAction === 'GUARDRAIL_INTERVENED' && {
+        guardrail_blocked: 'Task context blocked by content policy',
+      }),
     };
   } catch (err) {
     // Guardrail failures must propagate (fail-closed) — unscreened content must not reach the agent

cdk/test/handlers/shared/context-hydration.test.ts

@@ -546,6 +546,8 @@ describe('hydrateContext', () => {
         ok: true,
         json: async () => ({ number: 42, title: 'Bug', body: 'Details', comments: 0 }),
       });
+    // Guardrail screens assembled prompt when issue content is present
+    mockBedrockSend.mockResolvedValueOnce({ action: 'NONE' });
 
     const task = { ...baseTask, issue_number: 42, task_description: 'Fix it' };
     const result = await hydrateContext(task as any);
@@ -571,6 +573,9 @@ describe('hydrateContext', () => {
     expect(result.sources).toContain('task_description');
     expect(result.issue).toBeUndefined();
     expect(result.user_prompt).toContain('Fix it');
+    // No issue content fetched — guardrail should not be called (task_description already screened)
+    expect(result.guardrail_blocked).toBeUndefined();
+    expect(mockBedrockSend).not.toHaveBeenCalled();
   });
 
   test('no issue number — assembles from task description only', async () => {
@@ -628,6 +633,8 @@ describe('hydrateContext', () => {
       ok: true,
       json: async () => ({ number: 10, title: 'Test', body: 'body', comments: 0 }),
     });
+    // Guardrail screens assembled prompt when issue content is present
+    mockBedrockSend.mockResolvedValueOnce({ action: 'NONE' });
 
     const task = { ...baseTask, issue_number: 10, task_description: 'Fix' };
     const result = await hydrateContext(task as any, { githubTokenSecretArn: perRepoArn });
@@ -1027,7 +1034,7 @@ describe('screenWithGuardrail', () => {
 });
 
 // ---------------------------------------------------------------------------
-// hydrateContext — guardrail screening for PR tasks
+// hydrateContext — guardrail screening
 // ---------------------------------------------------------------------------
 
 describe('hydrateContext — guardrail screening', () => {
@@ -1113,29 +1120,70 @@ describe('hydrateContext — guardrail screening', () => {
     expect(mockBedrockSend).toHaveBeenCalledTimes(1);
   });
 
-  test('does not invoke guardrail for new_task type', async () => {
+  // --- new_task guardrail screening ---
+
+  const baseNewTask = {
+    task_id: 'TASK-NEW-001',
+    user_id: 'user-123',
+    status: 'SUBMITTED',
+    repo: 'org/repo',
+    branch_name: 'bgagent/TASK-NEW-001/fix',
+    channel_source: 'api',
+    status_created_at: 'SUBMITTED#2024-01-01T00:00:00Z',
+    created_at: '2024-01-01T00:00:00Z',
+    updated_at: '2024-01-01T00:00:00Z',
+    task_type: 'new_task',
+    task_description: 'Fix it',
+  };
+
+  function mockIssueFetch(): void {
     mockSmSend.mockResolvedValueOnce({ SecretString: 'ghp_test' });
     mockFetch.mockResolvedValueOnce({
       ok: true,
       json: async () => ({ number: 42, title: 'Bug', body: 'Details', comments: 0 }),
     });
+  }
 
-    const newTask = {
-      task_id: 'TASK-NEW-001',
-      user_id: 'user-123',
-      status: 'SUBMITTED',
-      repo: 'org/repo',
-      branch_name: 'bgagent/TASK-NEW-001/fix',
-      channel_source: 'api',
-      status_created_at: 'SUBMITTED#2024-01-01T00:00:00Z',
-      created_at: '2024-01-01T00:00:00Z',
-      updated_at: '2024-01-01T00:00:00Z',
-      task_type: 'new_task',
-      issue_number: 42,
-      task_description: 'Fix it',
-    };
-    const result = await hydrateContext(newTask as any);
+  test('invokes guardrail for new_task with issue content', async () => {
+    mockIssueFetch();
+    mockBedrockSend.mockResolvedValueOnce({ action: 'NONE' });
+
+    const result = await hydrateContext({ ...baseNewTask, issue_number: 42 } as any);
+    expect(result.guardrail_blocked).toBeUndefined();
+    expect(mockBedrockSend).toHaveBeenCalledTimes(1);
+  });
+
+  test('does not invoke guardrail for new_task without issue_number', async () => {
+    const result = await hydrateContext(baseNewTask as any);
     expect(result.guardrail_blocked).toBeUndefined();
     expect(mockBedrockSend).not.toHaveBeenCalled();
   });
+
+  test('returns guardrail_blocked when new_task issue context is blocked', async () => {
+    mockIssueFetch();
+    mockBedrockSend.mockResolvedValueOnce({ action: 'GUARDRAIL_INTERVENED' });
+
+    const result = await hydrateContext({ ...baseNewTask, issue_number: 42 } as any);
+    expect(result.guardrail_blocked).toBe('Task context blocked by content policy');
+    expect(mockBedrockSend).toHaveBeenCalledTimes(1);
+  });
+
+  test('proceeds normally when new_task issue context passes guardrail', async () => {
+    mockIssueFetch();
+    mockBedrockSend.mockResolvedValueOnce({ action: 'NONE' });
+
+    const result = await hydrateContext({ ...baseNewTask, issue_number: 42 } as any);
+    expect(result.guardrail_blocked).toBeUndefined();
+    expect(result.issue).toBeDefined();
+    expect(result.sources).toContain('issue');
+  });
+
+  test('throws when guardrail screening fails for new_task (fail-closed)', async () => {
+    mockIssueFetch();
+    mockBedrockSend.mockRejectedValueOnce(new Error('Bedrock timeout'));
+
+    await expect(
+      hydrateContext({ ...baseNewTask, issue_number: 42 } as any),
+    ).rejects.toThrow('Guardrail screening unavailable: Bedrock timeout');
+  });
 });

docs/design/OBSERVABILITY.md

@@ -129,6 +129,7 @@ Both are one-time, account-level setup steps — not managed by CDK.
 - **Guardrail screening events** — `guardrail_blocked` (content blocked by Bedrock Guardrail during hydration, with metadata: `reason`, `task_type`, `pr_number`, `sources`, `token_estimate`). Screening failures are logged with structured `metric_type` fields (not emitted as task events).
 - Time in each state (e.g. time in HYDRATING, time RUNNING, cold start to first agent activity).
 - Correlation with a task id and user id so users and operators can filter by task or user.
+- **Planned (Iteration 5, Phase 1): `PolicyDecisionEvent`** — A unified event schema for all policy decisions across the task lifecycle: admission control, budget/quota resolution, guardrail screening, tool-call interception, and finalization. Each event carries: decision ID, policy name, version, phase, input hash, result (`allow` | `deny` | `modify`), reason codes, and enforcement mode (`enforced` | `observed` | `steered`). This normalizes the current mix of structured events (e.g. `admission_rejected`, `guardrail_blocked`) and silent HTTP errors into a single auditable event type. See [ROADMAP.md Iteration 5](../guides/ROADMAP.md) (Centralized policy framework) and [SECURITY.md](./SECURITY.md) (Policy enforcement and audit).
 
 ### Agent execution
 

docs/design/ORCHESTRATOR.md

@@ -179,7 +179,7 @@ See the Admission control section for details. Validates that the task is allowe
 
 #### Step 2: Context hydration (deterministic)
 
-See the Context hydration section for details. Assembles the agent's prompt from multiple sources depending on task type. For `new_task`: user message, GitHub issue (title, body, comments), memory, repo configuration, and platform defaults. For `pr_iteration`: PR metadata, review comments, diff summary, and optional user instructions. An additional **pre-flight** sub-step verifies PR accessibility when `pr_number` is set (see [preflight.ts](../../cdk/src/handlers/shared/preflight.ts)). For PR tasks, the assembled prompt is screened through Amazon Bedrock Guardrails for prompt injection before the agent receives it. The output is a fully assembled prompt, ready to pass to the compute session.
+See the Context hydration section for details. Assembles the agent's prompt from multiple sources depending on task type. For `new_task`: user message, GitHub issue (title, body, comments), memory, repo configuration, and platform defaults. For `pr_iteration`: PR metadata, review comments, diff summary, and optional user instructions. An additional **pre-flight** sub-step verifies PR accessibility when `pr_number` is set (see [preflight.ts](../../cdk/src/handlers/shared/preflight.ts)). The assembled prompt is screened through Amazon Bedrock Guardrails for prompt injection before the agent receives it (PR tasks: always screened; `new_task`: screened when issue content is present). The output is a fully assembled prompt, ready to pass to the compute session.
 
 #### Step 3: Session start and agent execution (deterministic start + agentic execution)
 
@@ -253,6 +253,8 @@ Admission control runs immediately after the input gateway dispatches a "create
 - **Rejected.** Task transitions to `FAILED` with a reason (repo not onboarded, rate limit exceeded, concurrency limit, validation error). No counter change.
 - **Deduplicated.** Existing task ID returned. No new task created.
 
+**Planned (Iteration 5):** Admission control checks will be governed by Cedar policies as part of the centralized policy framework. Cedar replaces the current inline admission logic with formally verifiable policy evaluation — the same Cedar policy store handles admission, budget/quota resolution, tool-call interception, and (when multi-user/team lands) tenant-scoped authorization. All admission decisions will emit a structured `PolicyDecisionEvent` for audit. See [ROADMAP.md Iteration 5](../guides/ROADMAP.md) (Centralized policy framework) and [SECURITY.md](./SECURITY.md) (Policy enforcement and audit).
+
 ---
 
 ## Context hydration
@@ -271,7 +273,7 @@ The orchestrator's `hydrateAndTransition()` function calls `hydrateContext()` (`
 4. **Assembles the user prompt** based on task type:
    - **`new_task`**: A structured markdown document with Task ID, Repository, GitHub Issue section, and Task section. The format mirrors the Python `assemble_prompt()` in `agent/entrypoint.py`.
    - **`pr_iteration`**: Assembled by `assemblePrIterationPrompt()` — includes PR metadata (number, title, body), the diff summary (changed files and patches), review comments (inline and conversation), and optional user instructions from `task_description`.
-5. **Screens through Bedrock Guardrail** (PR tasks only): For `pr_iteration` and `pr_review` tasks, the assembled user prompt is screened through Amazon Bedrock Guardrails (`screenWithGuardrail()`) using the `PROMPT_ATTACK` content filter. If the guardrail detects prompt injection, `guardrail_blocked` is set on the result and the orchestrator fails the task. If the Bedrock API is unavailable, a `GuardrailScreeningError` is thrown (fail-closed — unscreened content never reaches the agent). Task descriptions for all task types are screened at submission time in `create-task-core.ts`.
+5. **Screens through Bedrock Guardrail** (PR tasks; `new_task` when issue content is present): The assembled user prompt is screened through Amazon Bedrock Guardrails (`screenWithGuardrail()`) using the `PROMPT_ATTACK` content filter. For `new_task` tasks without issue content, screening is skipped because the task description was already screened at submission time. If the guardrail detects prompt injection, `guardrail_blocked` is set on the result and the orchestrator fails the task. If the Bedrock API is unavailable, a `GuardrailScreeningError` is thrown (fail-closed — unscreened content never reaches the agent). Task descriptions for all task types are screened at submission time in `create-task-core.ts`.
 6. **Returns a `HydratedContext` object** containing `version`, `user_prompt`, `issue`, `sources`, `token_estimate`, `truncated`, and for `pr_iteration`/`pr_review` tasks: `resolved_branch_name` and `resolved_base_branch`.
 
 The hydrated context is passed to the agent as a new `hydrated_context` field in the invocation payload, alongside the existing legacy fields (`repo_url`, `task_id`, `branch_name`, `issue_number`, `prompt`). The agent checks for `hydrated_context` with `version == 1`; if present, it uses the pre-assembled `user_prompt` directly and skips in-container GitHub fetching and prompt assembly. If absent (e.g. during a deployment rollout or when the secret ARN isn't configured), the agent falls back to its existing behavior.