Merge branch 'main' into feat/deploy-yml

Author: scottschreckengaust

.dockerignore

@@ -0,0 +1,58 @@
+# Build context is repo root (see cdk/src/stacks/agent.ts) so the
+# Dockerfile can COPY contracts/ alongside agent/. Exclusions below
+# keep the context lean — without them the entire monorepo (CDK
+# cdk.out/, node_modules/, docs/dist/, etc.) gets uploaded on every
+# AgentCore deploy.
+
+# CDK output (recursive include if not excluded)
+cdk/cdk.out/
+cdk/lib/
+cdk/node_modules/
+
+# CLI and docs build artifacts
+cli/lib/
+cli/node_modules/
+docs/dist/
+docs/node_modules/
+docs/.astro/
+
+# Shared node_modules
+node_modules/
+
+# Agent venv and cache (rebuilt inside image via uv)
+agent/.venv/
+agent/__pycache__/
+agent/**/__pycache__/
+agent/**/*.pyc
+
+# Git and tooling
+.git/
+.prek/
+.claude/
+**/.DS_Store
+
+# Docs and assets not needed in image
+*.md
+*.png
+*.drawio
+*.html
+*.gif
+*.tape
+
+# Worktrees + scratch
+abca-worktrees/
+.next-session-prompt.md
+.e2e-test-plan.md
+
+# Test/coverage output
+coverage/
+**/coverage/
+.pytest_cache/
+**/.pytest_cache/
+
+# IDE / OS
+.idea/
+.vscode/
+yarn-error.log
+yarn-debug.log
+npm-debug.log*

.github/dependabot.yml

@@ -0,0 +1,61 @@
+version: 2
+
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "saturday"
+    cooldown:
+      default-days: 7
+    commit-message:
+      prefix: "chore(deps): actions"
+    open-pull-requests-limit: 1
+    groups:
+      all-actions:
+        patterns: ["*"]
+
+  - package-ecosystem: "docker"
+    directories:
+      - "**/*"
+    schedule:
+      interval: "weekly"
+      day: "saturday"
+    cooldown:
+      default-days: 7
+    commit-message:
+      prefix: "chore(deps): docker"
+    open-pull-requests-limit: 1
+    groups:
+      all-docker:
+        patterns: ["*"]
+
+  - package-ecosystem: "uv"
+    directories:
+      - "**/*"
+    schedule:
+      interval: "weekly"
+      day: "saturday"
+    cooldown:
+      default-days: 7
+    commit-message:
+      prefix: "chore(deps): uv"
+    open-pull-requests-limit: 1
+    groups:
+      all-python:
+        patterns: ["*"]
+
+  - package-ecosystem: "npm"
+    directories:
+      - "**/*"
+    schedule:
+      interval: "weekly"
+      day: "saturday"
+    cooldown:
+      default-days: 7
+    commit-message:
+      prefix: "chore(deps): npm"
+    open-pull-requests-limit: 1
+    groups:
+      all-npm:
+        patterns: ["*"]

.pre-commit-config.yaml

@@ -71,6 +71,22 @@ repos:
         exclude: ^docs/node_modules/
         stages: [pre-commit]
 
+      - id: types-sync-cdk-cli
+        name: type sync drift (CDK ↔ CLI)
+        entry: bash -lc 'cd "$(git rev-parse --show-toplevel)" && mise run check:types-sync'
+        language: system
+        pass_filenames: false
+        files: ^(cdk/src/handlers/shared/types\.ts$|cli/src/types\.ts$|scripts/check-types-sync\.ts$)
+        stages: [pre-commit]
+
+      - id: constants-sync
+        name: cross-language constants drift (contracts/constants.json)
+        entry: bash -lc 'cd "$(git rev-parse --show-toplevel)" && mise run check:constants-sync'
+        language: system
+        pass_filenames: false
+        files: ^(contracts/constants\.json$|agent/src/policy\.py$|cdk/src/handlers/shared/types\.ts$|cdk/src/constructs/blueprint\.ts$|scripts/check-constants-sync\.ts$)
+        stages: [pre-commit]
+
       - id: monorepo-security-pre-push
         name: security scans (pre-push)
         entry: bash -lc 'cd "$(git rev-parse --show-toplevel)" && mise run hooks:pre-push:security'

AGENTS.md

@@ -22,6 +22,7 @@ Use this routing before editing so the right package and tests get updated:
 | Agent runtime (clone, tools, prompts, container) | `agent/src/` (`pipeline.py`, `runner.py`, `config.py`, `hooks.py`, `policy.py`, `prompts/`, Dockerfile, etc.) | `agent/tests/`, `agent/README.md` for env/PAT |
 | Agent progress events (written to `TaskEventsTable` from the MicroVM; read by `bgagent watch`) | `agent/src/progress_writer.py`, `agent/src/pipeline.py` and `agent/src/runner.py` (integration points) | `agent/tests/test_progress_writer.py`; `cli/src/commands/watch.ts` for the consumer side |
 | User-facing or design prose | `docs/guides/`, `docs/design/` | Run **`mise //docs:sync`** or **`mise //docs:build`** (do not edit `docs/src/content/docs/` by hand) |
+| Architecture decisions (ADRs) | `docs/decisions/` | Run **`mise //docs:sync`** after adding or editing an ADR |
 | Monorepo tasks, CI glue | Root `mise.toml`, `scripts/`, `.github/workflows/` | — |
 
 ### CDK handler tests (quick map)
@@ -47,6 +48,7 @@ Handler entry tests: `cdk/test/handlers/orchestrate-task.test.ts`, `create-task.
 - **`prek install`** fails if Git **`core.hooksPath`** is set — another hook manager owns hooks; see [CONTRIBUTING.md](./CONTRIBUTING.md).
 - **Editing on `main` directly** — ALWAYS create a worktree with a feature branch for changes, even trivial ones. Main should stay clean; all work flows through worktree → branch → PR → merge.
 - **Git worktrees** — Always **`git fetch origin main`** before creating a new worktree to ensure you branch from the latest remote state. `node_modules/` and `agent/.venv/` are per-tree (not shared). Run **`mise run install`** in each new worktree before building. All CDK path references (`__dirname`-relative) and mise `config_roots` resolve correctly without extra setup.
+- **Bumping Cedar engines in isolation** — `cedarpy` (Python, `agent/pyproject.toml`) and `@cedar-policy/cedar-wasm` (TypeScript, `cdk/package.json`) are two language bindings over the same Cedar Rust core. They MUST move together; even patch-version drift between bindings can yield divergent `(decision, matching_rule_ids)` on the same `(policy, input)` — invisible to per-side unit tests, caught (only) by `contracts/cedar-parity/` golden fixtures in CI. If you bump one engine you MUST bump the other to a tested-compatible version AND refresh the parity fixtures in the same commit. Both pins are EXACT (no `^`/`~`). See `docs/design/CEDAR_HITL_GATES.md` §15.6 (decision #23) and the parity-contract banner in `mise.toml`. **DO NOT** accept upstream's "Update branch" or auto-merge suggestions on cedarpy without verifying parity with cedar-wasm.
 
 ### Tech stack
 

CONTRIBUTING.md

@@ -28,6 +28,7 @@ Guidelines:
 - If you change API types in `cdk/src/handlers/shared/types.ts`, update `cli/src/types.ts` to match.
 - If you change docs sources (`docs/guides/`, `docs/design/`), run `mise //docs:sync` so generated content stays in sync.
 - For significant features, add a design document to `docs/design/`.
+- For cross-cutting or hard-to-reverse decisions, add an ADR to `docs/decisions/` (see [ADR README](./docs/decisions/README.md)).
 
 ### 4. Commit
 

agent/.dockerignore

@@ -8,32 +8,37 @@ FROM --platform=$TARGETPLATFORM golang:1.26.3-bookworm AS gh-builder
 ARG GH_VERSION
 RUN GOPROXY=direct GOBIN=/out go install "github.com/cli/cli/v2/cmd/gh@v${GH_VERSION}"
 
-FROM --platform=$TARGETPLATFORM python:3.13-slim
+FROM --platform=$TARGETPLATFORM python:3.13-slim@sha256:dc1546eefcbe8caaa1f004f16ab76b204b5e1dbd58ff81b899f21cd40541232f
 
 # Install mise (polyglot dev tool manager)
 COPY --from=mise /usr/local/bin/mise /usr/local/bin/mise
 COPY --from=gh-builder /out/gh /usr/local/bin/gh
 
 # Install system dependencies in multiple layers:
-#   - Node.js 20 (required by Claude Code CLI)
+#   - Node.js 24 LTS (required by Claude Code CLI)
 #   - git (repo operations)
 #   - build-essential (native compilation for some repos)
 #   - curl (downloads)
 RUN apt-get update && \
+    # Patch any base-image CVEs that have a fix available in the
+    # current Debian point release. Without this, transitive system-
+    # library CVEs (e.g. libnghttp2 CVE-2026-27135) ride the base
+    # ``python:3.13-slim`` tag until upstream rebuilds, which can be
+    # weeks. ``--no-install-recommends`` keeps the upgrade narrow and
+    # reproducible — only already-installed packages get bumped.
+    apt-get upgrade -y --no-install-recommends && \
     apt-get install -y --no-install-recommends \
         curl \
         git \
         build-essential \
         ca-certificates \
         gnupg && \
-    # Upgrade base image's CVE-2026-27135 vulnerability
-    apt-get upgrade -y --no-install-recommends libnghttp2-14 && \
     # Cleanup early to keep peak disk usage low during builds.
     apt-get clean && \
     rm -rf /var/lib/apt/lists/* /var/cache/apt/archives/*
 
-# Node.js 20
-RUN curl -fsSL https://deb.nodesource.com/setup_20.x | bash - && \
+# Node.js 24 LTS (https://nodejs.org/en/about/previous-releases)
+RUN curl -fsSL https://deb.nodesource.com/setup_24.x | bash - && \
     apt-get update && \
     apt-get install -y --no-install-recommends nodejs && \
     apt-get clean && \
@@ -42,22 +47,35 @@ RUN curl -fsSL https://deb.nodesource.com/setup_20.x | bash - && \
 # Install Claude Code CLI (the Python SDK requires this binary)
 # Then update known vulnerable transitive packages where fixed versions exist.
 RUN npm install -g npm@latest && \
-    npm install -g @anthropic-ai/claude-code@2.1.139 && \
+    npm install -g @anthropic-ai/claude-code@2.1.142 && \
     CLAUDE_NPM_ROOT="$(npm root -g)/@anthropic-ai/claude-code" && \
     npm --prefix "${CLAUDE_NPM_ROOT}" update tar minimatch glob cross-spawn picomatch
 
-# Install uv (fast Python package manager)
-COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
+# Install uv (fast Python package manager) — pinned for reproducibility
+COPY --from=ghcr.io/astral-sh/uv:0.11.14 /uv /usr/local/bin/uv
 
-# Install Python dependencies via uv
-COPY pyproject.toml uv.lock /app/
+# Install Python dependencies via uv. Build context is repo root (set in
+# ``cdk/src/stacks/agent.ts``) so source paths are prefixed with ``agent/``.
+COPY agent/pyproject.toml agent/uv.lock /app/
 RUN uv sync --frozen --no-dev --directory /app
 
 # Copy agent code (ARG busts cache so file edits are always picked up)
 ARG CACHE_BUST=0
-COPY src/ /app/src/
-COPY prepare-commit-msg.sh /app/
-COPY test_sdk_smoke.py test_subprocess_threading.py /app/
+COPY agent/src/ /app/src/
+# Cedar HITL built-in policy files (hard_deny.cedar + soft_deny.cedar).
+# ``agent/src/policy.py::_POLICIES_DIR`` resolves to ``/app/policies``
+# at import time; without these files the PolicyEngine init raises
+# ``missing built-in hard-deny policies`` and every task fails at 0
+# turns before the agent even connects to the CLI. Discovered during
+# Chunk 10 E2E T2.2 — the Dockerfile previously only copied ``src/``.
+COPY agent/policies/ /app/policies/
+# Cross-language constants (S9). ``agent/src/policy.py`` reads
+# ``/app/contracts/constants.json`` at import; the same file is consumed
+# by ``cdk/src/handlers/shared/types.ts`` at synth time. See
+# ``contracts/README.md`` for the contract.
+COPY contracts/ /app/contracts/
+COPY agent/prepare-commit-msg.sh /app/
+COPY agent/test_sdk_smoke.py agent/test_subprocess_threading.py /app/
 
 # Create non-root user (Claude Code CLI refuses bypassPermissions as root)
 RUN useradd -m -s /bin/bash agent && \

agent/Dockerfile

@@ -38,7 +38,7 @@ run = "uvx ruff format --check"
 
 [tasks.typecheck]
 description = "Type check with ty"
-run = "uvx ty check"
+run = "uv run ty check"
 
 [tasks.test]
 description = "Run tests with pytest"
@@ -52,8 +52,12 @@ run = "uvx bandit[toml] -c pyproject.toml -r . --severity-level=high"
 
 [tasks."security:image"]
 description = "Scan container image with trivy"
+# Build context is repo root (..) so Dockerfile can COPY contracts/
+# alongside agent/ — matches cdk/src/stacks/agent.ts. Without -f and
+# the .. context, the build fails because COPY agent/... can't find
+# agent/ inside the agent/ directory.
 run = [
-  "docker image inspect bgagent-local:latest >/dev/null 2>&1 || (ARCH=\"$(uname -m)\"; PLATFORM=\"linux/arm64\"; if [ \"$ARCH\" = \"x86_64\" ]; then PLATFORM=\"linux/amd64\"; fi; docker build --build-arg TARGETPLATFORM=\"$PLATFORM\" --build-arg CACHE_BUST=\"$(date +%s)\" -t bgagent-local:latest .)",
+  "ARCH=\"$(uname -m)\"; PLATFORM=\"linux/arm64\"; if [ \"$ARCH\" = \"x86_64\" ]; then PLATFORM=\"linux/amd64\"; fi; docker build --build-arg TARGETPLATFORM=\"$PLATFORM\" --build-arg CACHE_BUST=\"$(date +%s)\" -f Dockerfile -t bgagent-local:latest ..",
   "trivy image --scanners vuln --ignore-unfixed --ignorefile .trivyignore --severity HIGH,CRITICAL --exit-code 1 bgagent-local:latest",
 ]
 

agent/mise.toml

@@ -0,0 +1,59 @@
+// Built-in hard-deny policy set for Cedar HITL engine.
+//
+// Hard-deny is ABSOLUTE: no --pre-approve scope and no blueprint `disable:`
+// directive can bypass these rules. See docs/design/CEDAR_HITL_GATES.md
+// §12.5 and decision #8.
+//
+// Every rule in this file MUST carry @tier("hard") + @rule_id annotations.
+// Adding a rule here expands the set of categorically-forbidden agent
+// actions; removing a rule requires a security review.
+
+// Base catch-all permit. Specific forbid rules below override.
+@rule_id("base_permit")
+permit (principal, action, resource);
+
+// pr_review tasks may never invoke Write. Absolute; cannot be overridden
+// by per-blueprint customization or --pre-approve.
+@tier("hard")
+@rule_id("pr_review_forbid_write")
+forbid (
+    principal == Agent::TaskAgent::"pr_review",
+    action == Agent::Action::"invoke_tool",
+    resource == Agent::Tool::"Write"
+);
+
+// pr_review tasks may never invoke Edit.
+@tier("hard")
+@rule_id("pr_review_forbid_edit")
+forbid (
+    principal == Agent::TaskAgent::"pr_review",
+    action == Agent::Action::"invoke_tool",
+    resource == Agent::Tool::"Edit"
+);
+
+// Reject `rm -rf /` and similar absolute-root destructive commands.
+@tier("hard")
+@rule_id("rm_slash")
+forbid (principal, action == Agent::Action::"execute_bash", resource)
+when { context.command like "*rm -rf /*" };
+
+// Reject writes into `.git/` at the repo root (breaks local git state).
+@tier("hard")
+@rule_id("write_git_internals")
+forbid (principal, action == Agent::Action::"write_file", resource)
+when { context.file_path like ".git/*" };
+
+// Reject writes into nested `.git/` directories (submodules, worktrees).
+@tier("hard")
+@rule_id("write_git_internals_nested")
+forbid (principal, action == Agent::Action::"write_file", resource)
+when { context.file_path like "*/.git/*" };
+
+// Reject any SQL DROP TABLE through Bash — agents should not be running
+// destructive DDL against production or dev databases without a human
+// in the loop. Hard-deny because even "just testing locally" is a common
+// vector for data loss (wrong DB connected via saved credentials).
+@tier("hard")
+@rule_id("drop_table")
+forbid (principal, action == Agent::Action::"execute_bash", resource)
+when { context.command like "*DROP TABLE*" };