calcifier 0.1.1__tar.gz

calcifier-0.1.1/.claude-plugin/marketplace.json

@@ -0,0 +1,15 @@
+{
+  "name": "calcifier",
+  "owner": {
+    "name": "Trail of Bits",
+    "url": "https://www.trailofbits.com"
+  },
+  "description": "Typed, executable Python recipes for Claude and Codex skills.",
+  "plugins": [
+    {
+      "name": "calcifier",
+      "source": "./plugins/calcifier",
+      "description": "Calcify, execute, debug, and update typed agent recipes"
+    }
+  ]
+}

calcifier-0.1.1/.github/dependabot.yml

@@ -0,0 +1,21 @@
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly
+    cooldown:
+      default-days: 7
+    groups:
+      all:
+        patterns: ["*"]
+
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    cooldown:
+      default-days: 7
+    groups:
+      all:
+        patterns: ["*"]

calcifier-0.1.1/.github/workflows/actionlint.yml

@@ -0,0 +1,38 @@
+name: Actionlint
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  actionlint:
+    name: actionlint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Install actionlint
+        run: |
+          set -euo pipefail
+          # Pinned to actionlint v1.7.12 release tarball.
+          ACTIONLINT_VERSION="1.7.12"
+          ACTIONLINT_SHA256="8aca8db96f1b94770f1b0d72b6dddcb1ebb8123cb3712530b08cc387b349a3d8"
+          curl -fsSL -o actionlint.tar.gz \
+            "https://github.com/rhysd/actionlint/releases/download/v${ACTIONLINT_VERSION}/actionlint_${ACTIONLINT_VERSION}_linux_amd64.tar.gz"
+          echo "${ACTIONLINT_SHA256}  actionlint.tar.gz" | sha256sum -c -
+          tar -xzf actionlint.tar.gz actionlint
+          chmod +x actionlint
+
+      - name: Run actionlint
+        run: ./actionlint -color

calcifier-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,181 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+env:
+  PYTHONWARNDEFAULTENCODING: "1"
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884  # v10.3.0
+
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
+        with:
+          python-version: "3.13"
+
+      - run: uv sync --all-groups --locked
+
+      - run: make lockcheck lint portable
+
+  type-check:
+    name: Type check (ty)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884  # v10.3.0
+
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
+        with:
+          python-version: "3.13"
+
+      - run: uv sync --all-groups --locked
+
+      - run: make typecheck
+
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # "Test (3.13)" and "Test (3.14)" are required status checks in the main
+        # branch ruleset; removing a version leaves its check pending forever.
+        python-version: ["3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884  # v10.3.0
+
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - run: uv sync --all-groups --locked
+
+      - run: uv run pytest -q -n auto tests/
+
+  windows-test:
+    name: Windows test (3.13)
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884  # v10.3.0
+
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
+        with:
+          python-version: "3.13"
+
+      - run: uv sync --all-groups --locked
+
+      - run: uv run pytest -q -n auto tests/
+
+  dep-audit:
+    name: Dependency audit (pip-audit)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884  # v10.3.0
+
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
+        with:
+          python-version: "3.13"
+
+      - name: Export locked requirements
+        run: |
+          uv export --frozen --all-groups --format requirements-txt \
+            --no-emit-project -o requirements-frozen.txt
+
+      - name: Run pip-audit against the lockfile export
+        run: uvx pip-audit -r requirements-frozen.txt --disable-pip --strict
+
+  coverage:
+    name: Coverage
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884  # v10.3.0
+
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
+        with:
+          python-version: "3.13"
+
+      - run: uv sync --all-groups --locked
+
+      - run: uv run coverage run --branch -m pytest -q tests/
+
+      - name: Coverage report (gate)
+        run: uv run coverage report
+
+      - name: Coverage XML for upload
+        run: uv run coverage xml -o coverage.xml
+
+      - name: Upload coverage XML
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9  # v7.0.2
+        with:
+          name: coverage-xml
+          path: coverage.xml
+
+  build:
+    name: Build sdist + wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884  # v10.3.0
+
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
+        with:
+          python-version: "3.13"
+
+      - name: Seed deliberately dirty workstation state
+        run: |
+          mkdir -p .claude .hypothesis .vivisect
+          touch .claude/release-leak .hypothesis/release-leak .vivisect/release-leak
+
+      - run: uv build
+
+      - name: Verify artifact contents and version surfaces
+        run: uv run python scripts/verify_artifacts.py dist/
+
+      - run: uvx twine check dist/*
+
+      - name: Smoke-import the wheel
+        run: |
+          python -m venv /tmp/wheel-check
+          /tmp/wheel-check/bin/pip install dist/*.whl
+          /tmp/wheel-check/bin/python -c "import calcifier; print(calcifier.__version__)"
+          /tmp/wheel-check/bin/calcifier --version

calcifier-0.1.1/.github/workflows/mutation.yml

@@ -0,0 +1,116 @@
+name: Mutation Testing
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  # Finish the costly report; keep only the newest pending commit in this group.
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  gremlins:
+    name: Mutation shard (${{ matrix.operator }}, ${{ matrix.index }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          # Balance complete modules by observed per-operator mutant runtime.
+          # Boolean has the most work; comparison was a single multi-hour job.
+          - {operator: comparison, index: 0, count: 4}
+          - {operator: comparison, index: 1, count: 4}
+          - {operator: comparison, index: 2, count: 4}
+          - {operator: comparison, index: 3, count: 4}
+          - {operator: arithmetic, index: 0, count: 2}
+          - {operator: arithmetic, index: 1, count: 2}
+          - {operator: boolean, index: 0, count: 8}
+          - {operator: boolean, index: 1, count: 8}
+          - {operator: boolean, index: 2, count: 8}
+          - {operator: boolean, index: 3, count: 8}
+          - {operator: boolean, index: 4, count: 8}
+          - {operator: boolean, index: 5, count: 8}
+          - {operator: boolean, index: 6, count: 8}
+          - {operator: boolean, index: 7, count: 8}
+          - {operator: boundary, index: 0, count: 2}
+          - {operator: boundary, index: 1, count: 2}
+          - {operator: return, index: 0, count: 4}
+          - {operator: return, index: 1, count: 4}
+          - {operator: return, index: 2, count: 4}
+          - {operator: return, index: 3, count: 4}
+    env:
+      ANTHROPIC_API_KEY: ""
+      OPENAI_API_KEY: ""
+      GREMLIN_OPERATORS: ${{ matrix.operator }}
+      GREMLIN_CACHE: "1"
+      SHARD_INDEX: ${{ matrix.index }}
+      SHARD_COUNT: ${{ matrix.count }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884  # v10.3.0
+
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
+        with:
+          python-version: "3.13"
+
+      # Reuse results only when the complete code and test inputs match. The
+      # plugin also hashes each target and its covering tests internally.
+      - uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9  # v6.1.0
+        with:
+          path: .gremlins_cache
+          key: gremlins-${{ runner.os }}-py313-${{ matrix.operator }}-${{ matrix.index }}of${{ matrix.count }}-${{ hashFiles('uv.lock', 'pyproject.toml', 'Makefile', 'src/**', 'tests/**', 'plugins/**', 'scripts/mutation_shards.py', 'scripts/mutation_weights.json', '.github/workflows/mutation.yml') }}
+
+      - run: uv sync --all-groups --locked
+
+      - name: Mutate this operator's module partition
+        run: |
+          set -euo pipefail
+          MUTATION_RUN_TARGETS="$(python3 scripts/mutation_shards.py --operator "$GREMLIN_OPERATORS" --index "$SHARD_INDEX" --count "$SHARD_COUNT")"
+          export MUTATION_RUN_TARGETS
+          make mutate
+          test -s coverage/gremlins/gremlins.json
+
+      - name: Upload report
+        if: always() && hashFiles('coverage/gremlins/gremlins.json') != ''
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9  # v7.0.2
+        with:
+          name: gremlins-report-${{ matrix.operator }}-${{ matrix.index }}
+          path: coverage/gremlins/
+
+  mutation-threshold:
+    name: Mutation Testing (pytest-gremlins)
+    if: always()
+    needs: gremlins
+    runs-on: ubuntu-latest
+    steps:
+      # A missing shard would silently shrink each module's denominator.
+      - name: Require every mutation shard
+        env:
+          SHARDS: ${{ needs.gremlins.result }}
+        run: test "$SHARDS" = success
+
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333  # v8.0.2
+        with:
+          pattern: "gremlins-report-*"
+          path: coverage/shards
+
+      # Report-only until v0.1.0 ships: the per-module rate is printed but does not fail CI.
+      - name: Report the per-module kill rate
+        continue-on-error: true
+        run: |
+          set -euo pipefail
+          mapfile -d '' reports < <(find coverage/shards -name gremlins.json -print0)
+          python3 scripts/mutation_threshold.py "${reports[@]}" --min 90

calcifier-0.1.1/.github/workflows/publish.yml

@@ -0,0 +1,127 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+# Releases are immutable and serialized through the GitHub release event;
+# we still set workflow-level concurrency so a botched re-tag of the same
+# release cannot race a previous publish run.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.release.tag_name }}
+  cancel-in-progress: false
+
+permissions: {}
+
+jobs:
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    env:
+      RELEASE_TAG: ${{ github.event.release.tag_name }}
+    steps:
+      - name: Verify release tag is a vX.Y.Z[-pre] version
+        run: |
+          set -euo pipefail
+          if ! printf '%s\n' "$RELEASE_TAG" \
+              | grep -Eq '^v[0-9]+\.[0-9]+\.[0-9]+(-(alpha|beta|rc)\.?[0-9]+)?$'; then
+            echo "release tag '$RELEASE_TAG' does not match a publishable pattern" >&2
+            exit 1
+          fi
+
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+          ref: ${{ github.event.release.tag_name }}
+
+      - name: Verify annotated signed tag and main reachability
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          git fetch --no-tags origin main
+          if [ "$(git cat-file -t "$RELEASE_TAG")" != tag ]; then
+            echo "$RELEASE_TAG is not an annotated tag" >&2
+            exit 1
+          fi
+          REF_JSON="$(gh api "repos/$GITHUB_REPOSITORY/git/ref/tags/$RELEASE_TAG")"
+          TAG_OBJECT="$(printf '%s' "$REF_JSON" | jq -r '.object.sha')"
+          TAG_JSON="$(gh api "repos/$GITHUB_REPOSITORY/git/tags/$TAG_OBJECT")"
+          if [ "$(printf '%s' "$TAG_JSON" | jq -r '.verification.verified')" != true ]; then
+            printf '%s\n' "$TAG_JSON" | jq '.verification' >&2
+            exit 1
+          fi
+          TAG_COMMIT="$(printf '%s' "$TAG_JSON" | jq -r '.object.sha')"
+          git merge-base --is-ancestor "$TAG_COMMIT" origin/main
+          test "$TAG_COMMIT" = "$(git rev-parse HEAD)"
+
+      - uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884  # v10.3.0
+        with:
+          # Release artifacts must not depend on caches writable by lower-trust workflows.
+          enable-cache: false
+
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
+        with:
+          python-version: "3.13"
+
+      - run: uv sync --all-groups --locked
+
+      - name: Verify every source version surface
+        run: uv run python scripts/verify_artifacts.py --source-only --release-tag "$RELEASE_TAG"
+
+      - name: Re-run release verification suite
+        run: |
+          make verify
+          uv run coverage run -m pytest -q tests/
+          uv run coverage report
+
+      - name: Audit locked dependencies
+        run: |
+          uv export --frozen --all-groups --format requirements-txt \
+            --no-emit-project -o requirements-frozen.txt
+          uvx pip-audit -r requirements-frozen.txt --disable-pip --strict
+
+      - run: uv build
+
+      - name: Verify artifact contents and versions
+        run: uv run python scripts/verify_artifacts.py dist/
+
+      - run: uvx twine check dist/*
+
+      - name: Smoke-import the wheel
+        run: |
+          set -euo pipefail
+          python -m venv /tmp/wheel-check
+          /tmp/wheel-check/bin/pip install dist/*.whl
+          /tmp/wheel-check/bin/calcifier --version
+
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9  # v7.0.2
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write       # OIDC trusted publishing for pypa/gh-action-pypi-publish.
+      attestations: write   # actions/attest-build-provenance signs the wheel + sdist.
+      contents: read        # Read-only checkout of release metadata.
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333  # v8.0.2
+        with:
+          name: dist
+          path: dist/
+
+      - uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8  # v4.2.2
+        with:
+          subject-path: "dist/*"
+
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33  # v1.14.2
+        with:
+          attestations: true

calcifier-0.1.1/.github/workflows/zizmor.yml

@@ -0,0 +1,29 @@
+name: Zizmor
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  actions: read  # zizmor needs read access to introspect workflow metadata.
+
+jobs:
+  zizmor:
+    name: Workflow Security Audit
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: zizmorcore/zizmor-action@cc914d7f3750a2d13d75c7f184a1060aa0e9d482  # v0.6.4
+        with:
+          version: "1.30.1"
+          advanced-security: false

calcifier-0.1.1/.gitignore

@@ -0,0 +1,27 @@
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/
+.calcifier-runtime/
+coverage/
+.gremlins_cache/
+.claude/
+.codex/
+.remember/
+.serena/
+.uv-cache/
+.vivisect/
+
+# Coverage artifacts
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+
+# Generated benchmark reports
+benchmarks/**/results/
+benchmarks/**/*-results/

calcifier-0.1.1/AGENTS.md

@@ -0,0 +1,53 @@
+# Working on Calcifier
+
+Calcifier turns a SKILL.md into a runnable Python workflow. Python handles
+repeatable operations; agents handle understanding, interpretation, and uncertain
+decisions. Preserve the skill's instructions, mandatory steps, and explicit
+output requirements, including required fields and word counts.
+Compiler behavior must stay independent of any particular skill or provider.
+
+## Code organization
+
+- `src/calcifier/` contains the compiler, runtime, and public package.
+  [docs/architecture.md](docs/architecture.md) maps their module boundaries.
+- `tests/` contains offline regression tests and neutral skill fixtures;
+  shared fixtures belong in `tests/support/`.
+- `scripts/` contains development tools, not runtime dependencies.
+- `docs/` contains detailed usage and design notes. Keep the README focused on
+  what Calcifier does, why someone would use it, and where to start.
+
+## Changes
+
+- Prefer deleting duplication to adding abstractions. Use existing helpers and
+  module boundaries; avoid speculative frameworks and compatibility layers.
+- Fix the general mechanism behind a failure. Do not add compiler rules, prompt
+  sentences, or tests tied to one skill's wording or domain.
+- When a recipe uses an API naturally, prefer supporting that use over adding a
+  rejection rule. Before adding a check, see whether ty, the dry run, or repair
+  already catches the failure.
+- Keep `calcifier.__all__` small. Generated recipes import only those names;
+  prefer extending an existing call over adding another public primitive.
+- Preserve behavior and validation unless the task explicitly changes them.
+  Do not weaken an assertion or replace a failed result with an unverified one
+  to make tests pass. Compatibility work needs a supported API or format to serve.
+- Keep rejection focused on behavioral defects: invalid code, certain runtime
+  failures, unsafe effects, and races. Formatting preferences and type precision
+  must not reject an otherwise runnable recipe.
+- Always attempt the whole compiler dry run with stub agents and synthesized
+  inputs. Preserve its limits and report coverage gaps as unverified, never passed.
+- Keep instruction handling direct; do not build fidelity proof machinery as a
+  substitute for compiling and running the recipe.
+
+## Verification and workflow
+
+- Run focused tests while editing, then `gmake verify`. This checks the lock,
+  Ruff, ty, portable plugin recipes, and the test suite. CI reports mutation
+  rates; do not run mutation testing locally.
+- Tests must use stub providers and never call live Claude/Codex CLIs. Write
+  byte-exact fixtures with explicit encoding/newline settings; cover LF and CRLF
+  when preserving source or resource bytes.
+- Live acceptance is owner-run. Do not inspect held-out fixtures, cohort lists,
+  or results, and do not run them yourself. Test the acceptance runner only with
+  neutral fixtures. Offline checks do not establish answer quality.
+- Work in an isolated checkout, preserve the owner's local changes, keep
+  generated evidence outside Git, and use normal pushes.

calcifier-0.1.1/CHANGELOG.md

@@ -0,0 +1,77 @@
+# Changelog
+
+## v0.1.1 — 2026-10-14
+
+Release metadata update for the first PyPI publication. The v0.1.0 GitHub
+release used an unsigned lightweight tag and failed the signed-tag publishing
+check. This release contains the features documented below for v0.1.0.
+
+## v0.1.0 — 2026-10-14
+
+First public release of Calcifier. Write Python workflows that combine
+repeatable operations with agent reasoning, or compile them from existing
+skills. Requires Python 3.13 or newer.
+
+### Added
+
+- **Python recipes.** Author workflows directly with `@recipe` and typed `@step`
+  functions, ordinary Python control flow, and async functions. Entry signatures
+  define typed CLI inputs. `fail()` aborts; `emit()` exposes named artifacts.
+- **Skill compilation.** Generate a reviewable Python recipe from a `SKILL.md`
+  and packaged resources. Repeatable operations move into Python; reasoning
+  stays with agents. Generation, static checks, whole-recipe stub execution,
+  and repairs share a bounded call/time budget.
+- **Runnable fallback.** Compilation starts from one agent session with the
+  intact skill. Failed optimization retains that baseline and reports
+  `baseline_retained`; `--require-compiled` preserves it but exits nonzero.
+- **Typed agent responses.** Closed `@output_type` records enforce required
+  fields, value types, and constraints such as allowed values and word counts.
+  Invalid responses receive one parse retry. Codex receives schemas through its
+  native structured-output channel; the host validates full Python types.
+- **Agent roles and budgets.** Configure Claude, Codex, or custom argv adapters
+  by semantic role. Steps, parallel workers, and children share call and wall
+  limits. `--max-agent-calls` bounds charged attempts, including parse retries,
+  without increasing declared limits.
+  `Budget.remaining_wall_seconds()` exposes the active run's effective time left.
+  Custom command adapters receive their effective timeout in the call contract.
+- **Instruction delivery.** File-based recipes pin original instructions and
+  references. `prepare_context()` bundles complete tasks and prior results
+  without duplicating prompts or changing the project working directory.
+- **Declared effects.** Contained, atomic report writes; artifact verification;
+  host argv commands; and soft/hard dry-run modes. `--output-dir` redirects a
+  declared root and protects existing files.
+- **Typed command results.** `run_command(..., output=T)` validates successful
+  JSON stdout. Compiler dry runs execute read-only commands and synthesize
+  suppressed mutating results, reporting unavailable inputs as unverified.
+- **Parallel checkpoints.** Serial `on_result` callbacks checkpoint completed
+  workers; `reuse_existing=True` adopts byte-identical artifacts for updates.
+- **Resources and composition.** Verified resource snapshots, pinned child
+  recipes, shared budgets/output roots, and dependency-ordered graph builds
+  with closed catalogs.
+- **Diagnostics and traces.** Compiler telemetry and incremental versioned run
+  traces record attempts, artifacts, effects, timing, budgets, and observed
+  usage. Missing usage remains unknown. `profile` summarizes a trace.
+- **CLI and plugin.** Compile, execute, debug, update-by-diff, portable lint,
+  graph builds, and profiling; four Claude Code plugin skills with recipes.
+
+### Security
+
+- **Trust and integrity.** Execution requires consent for exact recipe bytes,
+  resources, and child pins. Compilation does not grant trust; adjacent trust
+  files have no authority. Recipes execute Python with host permissions; review
+  the source and dependencies before granting trust.
+- **Behavioral checks.** Source checks reject certain runtime failures, unsafe
+  effects, model-controlled paths/commands, and races. Style and type precision
+  do not reject runnable candidates. Stub execution reports coverage gaps
+  without promoting them to passes.
+- **Provider boundaries.** Host agents use explicit filesystem contracts and
+  clean settings. Subprocesses run without a shell under time/output limits.
+- **Strict records and redaction.** Malformed trace/trust data fails closed.
+  Secret-like field names are redacted; free text still needs review.
+- **Release provenance.** A signed-tag release workflow checks source and
+  artifact versions, uses PyPI trusted publishing and build attestations, and
+  builds without workflow caches.
+
+See [usage](docs/usage.md), [architecture](docs/architecture.md), and
+[providers](docs/providers.md) for contracts and limits. Compilation and offline
+checks do not establish answer quality, instruction fidelity, or faster execution.