agentic-dev-loop 1.0.0a9__tar.gz → 1.0.0a11__tar.gz

{agentic_dev_loop-1.0.0a9 → agentic_dev_loop-1.0.0a11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-dev-loop
-Version: 1.0.0a9
+Version: 1.0.0a11
 Summary: Turn an LLM into a gated, sandboxed, resumable construction loop over your codebase.
 Author: Luke Wilson
 License-Expression: Apache-2.0
@@ -35,6 +35,7 @@ Requires-Dist: langgraph-checkpoint-sqlite>=3.0
 Provides-Extra: dev
 Requires-Dist: hypothesis>=6.0; extra == "dev"
 Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pip-audit>=2.0; extra == "dev"
 Dynamic: license-file
 
 # agentic-dev-loop
@@ -90,10 +91,27 @@ LLM timeout (agent runs are long).
 | LLM API key | The env var named by your pipeline's `api_key_env` (e.g. `OPENAI_API_KEY`) must be set — a missing key fails fast, naming it. |
 
 ```bash
-pip install "agentic-dev-loop==1.0.0a8"
+pip install "agentic-dev-loop==1.0.0a9"
 agentic-dev-loop --version
 ```
 
+The canonical consumer install is **pipx**, which puts the engine's venv
+*outside* the workspace — the sandbox mount set is exactly `{workspace}`, so an
+out-of-workspace install is unmounted and never agent-writable:
+
+```bash
+pipx install "agentic-dev-loop==1.0.0a9"
+```
+
+If you install with `uv` shortly after a release, pass `--refresh` — PyPI
+serves the package index with `Cache-Control: max-age=600`, and uv otherwise
+reuses a pre-upload snapshot of the index for up to 10 minutes, reporting
+"no version of agentic-dev-loop==X.Y.Z" for a version that is already live:
+
+```bash
+uv pip install --refresh "agentic-dev-loop==1.0.0a9"
+```
+
 On the first run the engine pulls the **digest-pinned** dev image
 (`ghcr.io/lukedawilson/agentic-dev-loop/dev`) and verifies its digest — the
 supply-chain check refuses to continue on a mismatch. If you're running
@@ -188,13 +206,16 @@ steps:
 
 | Key | Notes |
 | --- | --- |
-| `agent:` / `command:` / `action:` | Exactly one per step. Agents live in `agents_dir` as `<name>.agent.md`; commands run sandboxed (mechanical, never an LLM call); actions are registered host-side functions. |
+| `agent:` / `command:` / `action:` | Exactly one per step. Agents live in `agents_dir` as `<name>.agent.md`; commands run sandboxed (mechanical, never an LLM call). `commit` is the sole host-side built-in action; consumer actions are sandbox-executed, command-shaped scripts (see [Host boundary](#host-boundary-security-model)). |
 | `produces:` / `artifact:` + `verdicts:` | Hygiene-tracked outputs vs verdict-parsed routing. The **last** `VERDICT:` line wins; stale artifacts are deleted at each attempt start. |
 | `on_pass:` / `on_fail:` | A step name, terminal `success`/`failure`, or `{goto: X, retry: true}`. No loops happen unless you write them. |
 | `env:` / `setup:` / `network:` | `env:` declares step vars (fixed safe base + declared vars only); `setup:` provisions the sandbox (command steps, network ON, stamp-cached); `network: true` grants egress to a command or agent step (default off) — see [Per-stage networking](#per-stage-networking). |
 | `secrets:` (top-level) / step `secrets:` | Declares secret **refs only — never values**; each step opts in to the refs it needs. Resolved host-side and injected into that step's exec env only. See [Secrets](#secrets--refs-only-never-values). |
 | `isolation:` (optional) | Configures the sandbox — image override, resource caps, `allow_git_mutations`. It can never disable it. |
 | `state_dir` | Defaults to `~/.agentic-dev-loop/runs/<pipeline-hash>/` — artifacts and checkpoints live outside the sandbox mount. |
+| `extensions_dir` | Where consumer `extensions:` modules resolve — defaults to `~/.agentic-dev-loop/extensions`, **outside** the workspace. Workspace-resident extension/tool modules are refused at load. |
+| `deps_policy` | `locked` (default) or `open`. `locked` = the human-owned lockfile is the source of truth and the agent may not add dependencies; `open` = the bootstrap protocol (the agent may add exact-pinned manifest entries). See [Dependency policy](#dependency-policy-locked-by-default). |
+| `lockfiles` | The pipeline's declared lockfile names (workspace-relative), injected into agent context and named by the missing-dependency fail-fast. Required (non-empty) when `deps_policy: locked` — a `locked` pipeline with no lockfiles fails fast at load. |
 
 ### Secrets (`secrets:`) — refs only, never values
 
@@ -253,28 +274,149 @@ steps:
   sandbox container (`--read-only`, `--cap-drop ALL`, single workspace mount)
   on the Docker bridge network — the default network-none container is always
   created too, so no infrastructure work happens mid-run.
-- **Command and agent steps** may declare it. Action steps are host-side and
-  never take it (a load-time error).
+- **Command, agent, and sandbox-action steps** may declare it. The host-side
+  built-in `commit` action never takes it (refused once the registry is known).
 - **Author opt-in is the control.** A networked step gives its agent raw
   egress for that stage; the default stays network-off everywhere. Reserve it
   for stages that need it (QA, integration). The residual risk is documented
   in [docs/setup.md](docs/setup.md).
 
+## Dependency policy (locked by default)
+
+The supply-chain dial is a pipeline-level `deps_policy:` field, **locked by
+default**. The engine injects the policy into every agent step's context —
+the rule lives in the engine, not in hand-authored `dev.agent.md` prose (the
+class of rule that deadlocked the NuGet cache).
+
+```yaml
+deps_policy: locked    # or: open    (default: locked)
+lockfiles: [uv.lock]   # or: [packages.lock.json, package-lock.json]
+```
+
+- **`locked`** — the human-owned lockfile is the source of truth; the agent
+  may not add dependencies. The injected rule says *"You may only use
+  dependencies already present in `<lockfile>`. If the design requires a
+  dependency that is not present, declare it in your final response under the
+  fixed header `## Missing dependencies` (one `name==version` per line) and
+  finish what you can. Do not add it to the manifest."* A non-empty
+  `## Missing dependencies` declaration **fails the run fast** with
+  `Extend <lockfile> with these pins and re-run: …` — one human lockfile edit,
+  not a retry loop. The declaration is advisory to the human; the engine never
+  auto-fetches the declared packages.
+- **`open`** — the bootstrap protocol (018): the agent may add exact-pinned
+  manifest entries directly (never a package-manager `add` command); the
+  network-on restore step fetches them. The engine injects the same rule
+  canonically. Nothing about `open` is default.
+
+The **restore step** runs the toolchain's locked mode and fails when the
+manifest and lockfile disagree:
+
+| Toolchain | Locked restore | Lockfile |
+| --- | --- | --- |
+| .NET | `dotnet restore --locked-mode` | `packages.lock.json` (set `RestorePackagesWithLockFile=true`) |
+| node | `npm ci` | `package-lock.json` |
+| python | `uv sync --locked` (or pip-tools `pip-sync requirements.lock`) | `uv.lock` — pip has no native lockfile; `uv` is the canonical locked-install tool |
+
+### Audit escalation in the restore step
+
+The restore step also fails on known-CVE findings, at a per-toolchain
+threshold:
+
+| Toolchain | Audit (fails the step) |
+| --- | --- |
+| .NET | `NuGetAudit` at `error` — any audit finding fails the restore |
+| node | `npm audit --audit-level=high` |
+| python | `pip-audit` — any finding fails |
+
+Under `locked`, a failing audit means the lockfile pins a vulnerable version:
+the run fails and the human regenerates the lockfile at a patched version.
+Under `open`, the failure routes to `dev` like any restore failure — the dev
+agent can bump the pin, but that pin is audited again on the next pass, so
+the loop self-corrects.
+
+### Generating a lockfile
+
+A human generates the lockfile once, on a network machine, and commits it —
+the engine never fetches on the agent's behalf:
+
+```bash
+uv lock                 # python — writes uv.lock from pyproject.toml
+uv sync --locked        # installs exactly uv.lock; fails on any drift
+npm install --package-lock-only   # node — writes package-lock.json
+npm ci                  # installs exactly package-lock.json
+dotnet restore --use-lock-file   # .NET — writes packages.lock.json
+dotnet restore --locked-mode      # installs exactly packages.lock.json
+```
+
+Keep the lockfile tracked (do not gitignore it) and re-run the locked restore
+to prove it holds from a clean cache before setting `deps_policy: locked`.
+
+## Host boundary (security model)
+
+The orchestrator, tool layer, and the `commit` action run in the **host
+process** — they hold your credentials and your full user account, so the
+engine keeps anything agent-writable out of that process:
+
+- **Consumer actions are sandbox-executed.** An action you register via an
+  extension is a command-shaped script (`script + params`), run through the
+  same sandbox path as command steps — the exit code is the verdict, and the
+  code never runs in the host. Only the engine's trusted built-ins (`commit`,
+  document loaders) run host-side.
+- **Extensions load from outside the workspace.** `extensions_dir` defaults to
+  `~/.agentic-dev-loop/extensions`; at load time any extension or tool module
+  whose file resolves under the workspace is refused *before import*, naming
+  the file.
+- **The engine installs outside the workspace.** Install with pipx so the venv
+  is unmounted from the sandbox; a startup self-check refuses to run if
+  `agentic_dev_loop` resolves under the workspace (an editable install bypasses
+  everything).
+- **Tooling is read-only by the loop.** At run start the pipeline file,
+  `agents_dir`, `additional_files`, `aidlc-docs/`, and `tools/` must be
+  git-clean relative to HEAD — otherwise the run refuses, naming the dirty
+  files. The `commit` action excludes those paths from its sweep, so the loop
+  never commits its own tooling.
+- **`commit` stays host-side, deliberately.** It holds push credentials; moving
+  it into the sandbox would trade host-exec-of-trusted-code for
+  credential-in-sandbox. It runs argv-style with a scrubbed child env and
+  `-c core.hooksPath=~/.agentic-dev-loop/state/hooks` so repo hooks never
+  execute.
+
+Net: the host executes nothing from the workspace, reads only git-clean
+control files, and the only agent-writable host-consumed thing left is the code
+the loop is building.
+
+### Consumer migration notes
+
+- **Actions** — replace a host-side `fn` registration with
+  `registry.add_sandbox_action(name, script)`. `script` is a command string
+  rendered with the step's `params:` plus `{subject}`; the exit code is the
+  verdict. `add_action` (host-side) is now engine-built-in-only and is refused
+  from extensions.
+- **Extensions** — move workspace-resident extension modules (e.g.
+  `extensions/*.py`) into `~/.agentic-dev-loop/extensions/` (or whatever
+  `extensions_dir:` names), and reinstall the engine via pipx so it is not
+  editable/in-workspace.
+- **Tooling** — commit the pipeline, agent defs, shared `additional_files`,
+  `aidlc-docs/`, and `tools/` before running: the run refuses dirty tooling,
+  and `commit` never commits it.
+
 ## Development environment
 
 ```bash
 git clone git@github.com:lukedawilson/agentic-dev-loop.git
 cd agentic-dev-loop
-./setup-venv.sh                       # idempotent .venv setup (never touches bare pip)
+pipx install "agentic-dev-loop==1.0.0a9"   # engine venv OUTSIDE the workspace (self-check)
 export OPENAI_API_KEY=...           # set your LLM key in the host env (no .env in the repo)
-python -m pytest tests/ -q            # fast suite
+python -m pytest tests/ -q            # fast suite (in-repo .venv is for tests only)
 python -m pytest tests/ -q -m "not docker"   # skip engine-dependent tests
-./trigger-agentic-dev-loop.sh --dry-run      # run the shipped pipeline against this repo
+agentic-dev-loop agentic-dev-loop/pipeline.yaml --dry-run   # run the shipped pipeline
 ./run-demo.sh                         # viz demo — scripted run replay, no pipeline needed
 ```
 
-- `setup-venv.sh` is safe to re-run and picks the right interpreter even on
-  machines with exotic Python installations.
+- `setup-venv.sh` builds the throwaway `.venv` for local `pytest` runs (the
+  pipeline's `test` step provisions its own `.venv-sandbox` inside the
+  sandbox). The loop itself must run from the pipx install — never an
+  in-workspace `.venv`, which the startup self-check refuses.
 - Docker-marked integration tests need a local daemon; CI runs them on Linux.
 - The shipped pipeline (`agentic-dev-loop/pipeline.yaml`) **dogfoods the tool on
   its own repo** — dev → test → review → qa → commit, with the engine's own

{agentic_dev_loop-1.0.0a9 → agentic_dev_loop-1.0.0a11}/README.md

@@ -51,10 +51,27 @@ LLM timeout (agent runs are long).
 | LLM API key | The env var named by your pipeline's `api_key_env` (e.g. `OPENAI_API_KEY`) must be set — a missing key fails fast, naming it. |
 
 ```bash
-pip install "agentic-dev-loop==1.0.0a8"
+pip install "agentic-dev-loop==1.0.0a9"
 agentic-dev-loop --version
 ```
 
+The canonical consumer install is **pipx**, which puts the engine's venv
+*outside* the workspace — the sandbox mount set is exactly `{workspace}`, so an
+out-of-workspace install is unmounted and never agent-writable:
+
+```bash
+pipx install "agentic-dev-loop==1.0.0a9"
+```
+
+If you install with `uv` shortly after a release, pass `--refresh` — PyPI
+serves the package index with `Cache-Control: max-age=600`, and uv otherwise
+reuses a pre-upload snapshot of the index for up to 10 minutes, reporting
+"no version of agentic-dev-loop==X.Y.Z" for a version that is already live:
+
+```bash
+uv pip install --refresh "agentic-dev-loop==1.0.0a9"
+```
+
 On the first run the engine pulls the **digest-pinned** dev image
 (`ghcr.io/lukedawilson/agentic-dev-loop/dev`) and verifies its digest — the
 supply-chain check refuses to continue on a mismatch. If you're running
@@ -149,13 +166,16 @@ steps:
 
 | Key | Notes |
 | --- | --- |
-| `agent:` / `command:` / `action:` | Exactly one per step. Agents live in `agents_dir` as `<name>.agent.md`; commands run sandboxed (mechanical, never an LLM call); actions are registered host-side functions. |
+| `agent:` / `command:` / `action:` | Exactly one per step. Agents live in `agents_dir` as `<name>.agent.md`; commands run sandboxed (mechanical, never an LLM call). `commit` is the sole host-side built-in action; consumer actions are sandbox-executed, command-shaped scripts (see [Host boundary](#host-boundary-security-model)). |
 | `produces:` / `artifact:` + `verdicts:` | Hygiene-tracked outputs vs verdict-parsed routing. The **last** `VERDICT:` line wins; stale artifacts are deleted at each attempt start. |
 | `on_pass:` / `on_fail:` | A step name, terminal `success`/`failure`, or `{goto: X, retry: true}`. No loops happen unless you write them. |
 | `env:` / `setup:` / `network:` | `env:` declares step vars (fixed safe base + declared vars only); `setup:` provisions the sandbox (command steps, network ON, stamp-cached); `network: true` grants egress to a command or agent step (default off) — see [Per-stage networking](#per-stage-networking). |
 | `secrets:` (top-level) / step `secrets:` | Declares secret **refs only — never values**; each step opts in to the refs it needs. Resolved host-side and injected into that step's exec env only. See [Secrets](#secrets--refs-only-never-values). |
 | `isolation:` (optional) | Configures the sandbox — image override, resource caps, `allow_git_mutations`. It can never disable it. |
 | `state_dir` | Defaults to `~/.agentic-dev-loop/runs/<pipeline-hash>/` — artifacts and checkpoints live outside the sandbox mount. |
+| `extensions_dir` | Where consumer `extensions:` modules resolve — defaults to `~/.agentic-dev-loop/extensions`, **outside** the workspace. Workspace-resident extension/tool modules are refused at load. |
+| `deps_policy` | `locked` (default) or `open`. `locked` = the human-owned lockfile is the source of truth and the agent may not add dependencies; `open` = the bootstrap protocol (the agent may add exact-pinned manifest entries). See [Dependency policy](#dependency-policy-locked-by-default). |
+| `lockfiles` | The pipeline's declared lockfile names (workspace-relative), injected into agent context and named by the missing-dependency fail-fast. Required (non-empty) when `deps_policy: locked` — a `locked` pipeline with no lockfiles fails fast at load. |
 
 ### Secrets (`secrets:`) — refs only, never values
 
@@ -214,28 +234,149 @@ steps:
   sandbox container (`--read-only`, `--cap-drop ALL`, single workspace mount)
   on the Docker bridge network — the default network-none container is always
   created too, so no infrastructure work happens mid-run.
-- **Command and agent steps** may declare it. Action steps are host-side and
-  never take it (a load-time error).
+- **Command, agent, and sandbox-action steps** may declare it. The host-side
+  built-in `commit` action never takes it (refused once the registry is known).
 - **Author opt-in is the control.** A networked step gives its agent raw
   egress for that stage; the default stays network-off everywhere. Reserve it
   for stages that need it (QA, integration). The residual risk is documented
   in [docs/setup.md](docs/setup.md).
 
+## Dependency policy (locked by default)
+
+The supply-chain dial is a pipeline-level `deps_policy:` field, **locked by
+default**. The engine injects the policy into every agent step's context —
+the rule lives in the engine, not in hand-authored `dev.agent.md` prose (the
+class of rule that deadlocked the NuGet cache).
+
+```yaml
+deps_policy: locked    # or: open    (default: locked)
+lockfiles: [uv.lock]   # or: [packages.lock.json, package-lock.json]
+```
+
+- **`locked`** — the human-owned lockfile is the source of truth; the agent
+  may not add dependencies. The injected rule says *"You may only use
+  dependencies already present in `<lockfile>`. If the design requires a
+  dependency that is not present, declare it in your final response under the
+  fixed header `## Missing dependencies` (one `name==version` per line) and
+  finish what you can. Do not add it to the manifest."* A non-empty
+  `## Missing dependencies` declaration **fails the run fast** with
+  `Extend <lockfile> with these pins and re-run: …` — one human lockfile edit,
+  not a retry loop. The declaration is advisory to the human; the engine never
+  auto-fetches the declared packages.
+- **`open`** — the bootstrap protocol (018): the agent may add exact-pinned
+  manifest entries directly (never a package-manager `add` command); the
+  network-on restore step fetches them. The engine injects the same rule
+  canonically. Nothing about `open` is default.
+
+The **restore step** runs the toolchain's locked mode and fails when the
+manifest and lockfile disagree:
+
+| Toolchain | Locked restore | Lockfile |
+| --- | --- | --- |
+| .NET | `dotnet restore --locked-mode` | `packages.lock.json` (set `RestorePackagesWithLockFile=true`) |
+| node | `npm ci` | `package-lock.json` |
+| python | `uv sync --locked` (or pip-tools `pip-sync requirements.lock`) | `uv.lock` — pip has no native lockfile; `uv` is the canonical locked-install tool |
+
+### Audit escalation in the restore step
+
+The restore step also fails on known-CVE findings, at a per-toolchain
+threshold:
+
+| Toolchain | Audit (fails the step) |
+| --- | --- |
+| .NET | `NuGetAudit` at `error` — any audit finding fails the restore |
+| node | `npm audit --audit-level=high` |
+| python | `pip-audit` — any finding fails |
+
+Under `locked`, a failing audit means the lockfile pins a vulnerable version:
+the run fails and the human regenerates the lockfile at a patched version.
+Under `open`, the failure routes to `dev` like any restore failure — the dev
+agent can bump the pin, but that pin is audited again on the next pass, so
+the loop self-corrects.
+
+### Generating a lockfile
+
+A human generates the lockfile once, on a network machine, and commits it —
+the engine never fetches on the agent's behalf:
+
+```bash
+uv lock                 # python — writes uv.lock from pyproject.toml
+uv sync --locked        # installs exactly uv.lock; fails on any drift
+npm install --package-lock-only   # node — writes package-lock.json
+npm ci                  # installs exactly package-lock.json
+dotnet restore --use-lock-file   # .NET — writes packages.lock.json
+dotnet restore --locked-mode      # installs exactly packages.lock.json
+```
+
+Keep the lockfile tracked (do not gitignore it) and re-run the locked restore
+to prove it holds from a clean cache before setting `deps_policy: locked`.
+
+## Host boundary (security model)
+
+The orchestrator, tool layer, and the `commit` action run in the **host
+process** — they hold your credentials and your full user account, so the
+engine keeps anything agent-writable out of that process:
+
+- **Consumer actions are sandbox-executed.** An action you register via an
+  extension is a command-shaped script (`script + params`), run through the
+  same sandbox path as command steps — the exit code is the verdict, and the
+  code never runs in the host. Only the engine's trusted built-ins (`commit`,
+  document loaders) run host-side.
+- **Extensions load from outside the workspace.** `extensions_dir` defaults to
+  `~/.agentic-dev-loop/extensions`; at load time any extension or tool module
+  whose file resolves under the workspace is refused *before import*, naming
+  the file.
+- **The engine installs outside the workspace.** Install with pipx so the venv
+  is unmounted from the sandbox; a startup self-check refuses to run if
+  `agentic_dev_loop` resolves under the workspace (an editable install bypasses
+  everything).
+- **Tooling is read-only by the loop.** At run start the pipeline file,
+  `agents_dir`, `additional_files`, `aidlc-docs/`, and `tools/` must be
+  git-clean relative to HEAD — otherwise the run refuses, naming the dirty
+  files. The `commit` action excludes those paths from its sweep, so the loop
+  never commits its own tooling.
+- **`commit` stays host-side, deliberately.** It holds push credentials; moving
+  it into the sandbox would trade host-exec-of-trusted-code for
+  credential-in-sandbox. It runs argv-style with a scrubbed child env and
+  `-c core.hooksPath=~/.agentic-dev-loop/state/hooks` so repo hooks never
+  execute.
+
+Net: the host executes nothing from the workspace, reads only git-clean
+control files, and the only agent-writable host-consumed thing left is the code
+the loop is building.
+
+### Consumer migration notes
+
+- **Actions** — replace a host-side `fn` registration with
+  `registry.add_sandbox_action(name, script)`. `script` is a command string
+  rendered with the step's `params:` plus `{subject}`; the exit code is the
+  verdict. `add_action` (host-side) is now engine-built-in-only and is refused
+  from extensions.
+- **Extensions** — move workspace-resident extension modules (e.g.
+  `extensions/*.py`) into `~/.agentic-dev-loop/extensions/` (or whatever
+  `extensions_dir:` names), and reinstall the engine via pipx so it is not
+  editable/in-workspace.
+- **Tooling** — commit the pipeline, agent defs, shared `additional_files`,
+  `aidlc-docs/`, and `tools/` before running: the run refuses dirty tooling,
+  and `commit` never commits it.
+
 ## Development environment
 
 ```bash
 git clone git@github.com:lukedawilson/agentic-dev-loop.git
 cd agentic-dev-loop
-./setup-venv.sh                       # idempotent .venv setup (never touches bare pip)
+pipx install "agentic-dev-loop==1.0.0a9"   # engine venv OUTSIDE the workspace (self-check)
 export OPENAI_API_KEY=...           # set your LLM key in the host env (no .env in the repo)
-python -m pytest tests/ -q            # fast suite
+python -m pytest tests/ -q            # fast suite (in-repo .venv is for tests only)
 python -m pytest tests/ -q -m "not docker"   # skip engine-dependent tests
-./trigger-agentic-dev-loop.sh --dry-run      # run the shipped pipeline against this repo
+agentic-dev-loop agentic-dev-loop/pipeline.yaml --dry-run   # run the shipped pipeline
 ./run-demo.sh                         # viz demo — scripted run replay, no pipeline needed
 ```
 
-- `setup-venv.sh` is safe to re-run and picks the right interpreter even on
-  machines with exotic Python installations.
+- `setup-venv.sh` builds the throwaway `.venv` for local `pytest` runs (the
+  pipeline's `test` step provisions its own `.venv-sandbox` inside the
+  sandbox). The loop itself must run from the pipx install — never an
+  in-workspace `.venv`, which the startup self-check refuses.
 - Docker-marked integration tests need a local daemon; CI runs them on Linux.
 - The shipped pipeline (`agentic-dev-loop/pipeline.yaml`) **dogfoods the tool on
   its own repo** — dev → test → review → qa → commit, with the engine's own

{agentic_dev_loop-1.0.0a9 → agentic_dev_loop-1.0.0a11}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agentic-dev-loop"
-version = "1.0.0a9"
+version = "1.0.0a11"
 description = "Turn an LLM into a gated, sandboxed, resumable construction loop over your codebase."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -55,6 +55,7 @@ agentic-dev-loop = "agentic_dev_loop.engine.cli:main"
 dev = [
     "hypothesis>=6.0",
     "pytest>=8.0",
+    "pip-audit>=2.0",
 ]
 
 [tool.setuptools.packages.find]

{agentic_dev_loop-1.0.0a9 → agentic_dev_loop-1.0.0a11}/src/agentic_dev_loop/core/config.py

@@ -114,7 +114,7 @@ class StepConfig(BaseModel):
     timeout: float | None = Field(default=None, gt=0)  # seconds, command steps only
     env: dict[str, str | None] | None = None  # NFR-1: null = inherit host value
     setup: str | None = None  # BR-13: command steps only
-    network: bool = False  # per-stage egress (command + agent steps; action steps reject)
+    network: bool = False  # per-stage egress (command/agent + sandbox actions; host-side actions reject at registry time)
     secrets: list[str] = []  # declared ref names; action steps reject
     on_pass: RouteTarget | None = None
     on_fail: RouteTarget | None = None
@@ -173,11 +173,11 @@ class StepConfig(BaseModel):
             raise ValueError(
                 f"step {self.name!r}: 'setup' is only allowed on 'command' steps"
             )
-        if self.network and self.action is not None:
-            raise ValueError(
-                f"step {self.name!r}: 'network' is only allowed on 'agent' or "
-                "'command' steps"
-            )
+        # `network` is NOT rejected here: the schema can't tell a host-side
+        # built-in action (e.g. `commit`, which must never take egress) from
+        # a sandbox-executed consumer action (which may, like a command step).
+        # That distinction is enforced once the registry is known — see
+        # `validate_action_network` (020).
         if self.secrets and self.action is not None:
             raise ValueError(
                 f"step {self.name!r}: 'secrets' is only allowed on 'agent' or "
@@ -201,6 +201,11 @@ class PipelineConfig(BaseModel):
     name: str
     extensions: list[str] = []
     additional_files: list[str] = []
+    # Where consumer `extensions:` modules resolve (work item 020). Must live
+    # OUTSIDE the workspace — the host refuses workspace-resident extension and
+    # tool-handler modules, so agent-writable files are never imported by the
+    # host process.
+    extensions_dir: str = "~/.agentic-dev-loop/extensions"
     env_allowlist: list[str] = []
     llm: LlmConfig
     isolation: IsolationConfig | None = None  # None = always-on defaults
@@ -209,6 +214,27 @@ class PipelineConfig(BaseModel):
     max_attempts: int = 3
     agents_dir: str
     steps: list[StepConfig] = Field(min_length=1)
+    # 021 supply-chain dependency dial: `locked` (default) = the human-owned
+    # lockfile is the source of truth and the agent may not add dependencies;
+    # `open` = the bootstrap protocol (the agent may add exact-pinned manifest
+    # entries for the restore step to fetch). `lockfiles` names the pipeline's
+    # declared lockfile(s) — injected into agent context and named by the
+    # missing-dependency fail-fast.
+    deps_policy: str = "locked"
+    lockfiles: list[str] = []
+
+    @field_validator("deps_policy")
+    @classmethod
+    def _known_deps_policy(cls, v: str) -> str:
+        if v not in ("locked", "open"):
+            raise ValueError(
+                f"deps_policy must be 'locked' or 'open', got {v!r}")
+        return v
+
+    @field_validator("lockfiles", mode="before")
+    @classmethod
+    def _coerce_lockfiles(cls, v: Any) -> Any:
+        return [v] if isinstance(v, str) else v
 
     @field_validator("secrets", mode="before")
     @classmethod
@@ -227,6 +253,15 @@ class PipelineConfig(BaseModel):
                     "values never belong in the pipeline yaml")
         return v
 
+    @model_validator(mode="after")
+    def _locked_requires_lockfiles(self) -> "PipelineConfig":
+        if self.deps_policy == "locked" and not self.lockfiles:
+            raise ValueError(
+                "deps_policy 'locked' requires at least one entry in "
+                "'lockfiles:' — name the lockfile(s) the locked boundary "
+                "enforces, or set 'deps_policy: open'")
+        return self
+
     @model_validator(mode="after")
     def _check_graph(self) -> "PipelineConfig":
         names = [s.name for s in self.steps]

{agentic_dev_loop-1.0.0a9 → agentic_dev_loop-1.0.0a11}/src/agentic_dev_loop/engine/actions.py

@@ -186,6 +186,23 @@ def checkpoint_exclude_pathspec(state_dir: str | None, cwd: Path) -> str | None:
     return f":(exclude){rel}/*.sqlite*"
 
 
+def tooling_exclude_pathspec(tooling_paths: list[str] | None) -> list[str]:
+    """git pathspecs excluding tooling paths from ``git add -A`` (020).
+
+    The loop must never commit its own tooling (pipeline, agent defs,
+    additional files, aidlc-docs, tools): the run-start integrity check
+    requires those paths to be clean relative to HEAD, so the auto-commit
+    must sweep everything *except* them. Empty when there is nothing to
+    exclude."""
+    specs = []
+    for rel in (tooling_paths or []):
+        rel = rel.replace(os.sep, "/")
+        if rel in ("", ".", ".."):
+            continue
+        specs.append(f":(exclude){rel}")
+    return specs
+
+
 def commit(state: dict, params: dict) -> dict:
     """The pipeline's only commit point. Skipped loudly when the worktree was
     dirty at run start, so the auto-commit can never swallow pre-existing
@@ -205,9 +222,13 @@ def commit(state: dict, params: dict) -> dict:
     cwd = Path.cwd()
     hooks = _trusted_hooks_dir()
     add_argv = ["-c", f"core.hooksPath={hooks}", "add", "-A"]
-    exclude = checkpoint_exclude_pathspec(state.get("state_dir"), cwd)
-    if exclude:
-        add_argv += ["--", exclude]
+    excludes = []
+    checkpoint_exclude = checkpoint_exclude_pathspec(state.get("state_dir"), cwd)
+    if checkpoint_exclude:
+        excludes.append(checkpoint_exclude)
+    excludes.extend(tooling_exclude_pathspec(state.get("tooling_paths")))
+    if excludes:
+        add_argv += ["--", *excludes]
     added = _git(add_argv, cwd=cwd)
     if added.returncode != 0:
         # The add is the step that touches the most files (a locked DB, a

{agentic_dev_loop-1.0.0a9 → agentic_dev_loop-1.0.0a11}/src/agentic_dev_loop/engine/cli.py

@@ -71,7 +71,8 @@ def _registry_for(cfg_path: Path) -> tuple[Registry, PipelineConfig]:
     run path instead of being rebuilt."""
     cfg = load_config(cfg_path)
     registry = default_registry()
-    load_extensions(cfg.extensions, registry)
+    load_extensions(cfg.extensions, registry,
+                    extensions_dir=cfg.extensions_dir, workspace=Path.cwd())
     return registry, cfg
 
 

agentic_dev_loop-1.0.0a11/src/agentic_dev_loop/engine/deps.py

@@ -0,0 +1,77 @@
+"""Supply-chain dependency dial (021): canonical policy injection and
+missing-dependency declaration parsing.
+
+The rule text lives HERE, in the engine, not in consumer `dev.agent.md` prose
+— the hand-authored rule is exactly the class that deadlocked the NuGet cache
+in 018. `deps_policy: locked` (the default) bounds the agent to the
+human-owned lockfile and fails a run fast when an agent declares a missing
+dependency; `deps_policy: open` injects the bootstrap protocol (the agent may
+add exact-pinned manifest entries for the restore step to fetch).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from agentic_dev_loop.core.config import PipelineConfig
+
+MISSING_DEPS_HEADER = "## Missing dependencies"
+
+_LOCKED_TEMPLATE = (
+    "You may only use dependencies already present in {lockfiles}. If the "
+    "design requires a dependency that is not present, declare it in your "
+    "final response under the fixed header `{header}` (one `name==version` "
+    "per line) and finish what you can. Do not add it to the manifest."
+)
+
+_OPEN_TEXT = (
+    "If the design needs a dependency that is not already present, add the "
+    "exact-pinned entry to the dependency manifest directly (do not run a "
+    "package-manager `add` command — it may need the network). Your offline "
+    "builds may fail until the restore step fetches it — that is expected; "
+    "write the code to match and leave the manifest entry in place."
+)
+
+
+def _lockfile_label(cfg: "PipelineConfig") -> str:
+    if cfg.lockfiles:
+        return ", ".join(f"`{name}`" for name in cfg.lockfiles)
+    return "the lockfile"
+
+
+def policy_injection(cfg: "PipelineConfig") -> str:
+    """The canonical dependency-policy paragraph injected into every agent
+    step's context, keyed on ``deps_policy`` and the declared lockfiles."""
+    if cfg.deps_policy == "open":
+        return _OPEN_TEXT
+    return _LOCKED_TEMPLATE.format(
+        lockfiles=_lockfile_label(cfg), header=MISSING_DEPS_HEADER)
+
+
+def parse_missing_dependencies(text: str | None) -> list[str]:
+    """Parse a final agent response for the fixed ``## Missing dependencies``
+    section. Returns the declared pins (one non-empty line each) beneath the
+    header, until the next ``## `` section or end of text. An absent header or
+    an empty/malformed section yields an empty list — only a non-empty
+    declaration triggers the fail-fast."""
+    if not text:
+        return []
+    lines = text.splitlines()
+    for i, line in enumerate(lines):
+        if line.strip() == MISSING_DEPS_HEADER:
+            pins: list[str] = []
+            for rest in lines[i + 1:]:
+                if rest.startswith("## "):
+                    break
+                stripped = rest.strip()
+                if stripped:
+                    pins.append(stripped)
+            return pins
+    return []
+
+
+def extension_message(cfg: "PipelineConfig", pins: list[str]) -> str:
+    """The fail-fast message naming the lockfile(s) and the declared pins."""
+    return (f"Extend {_lockfile_label(cfg)} with these pins and re-run:\n\n"
+            + "\n".join(pins))