agentagon 0.1.0__tar.gz

agentagon-0.1.0/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "ag",
+  "version": "0.1.0",
+  "description": "Review local changes, audit agent applications, and evaluate measured improvements.",
+  "author": {"name": "Agentagon"},
+  "license": "Apache-2.0",
+  "skills": "./skills/"
+}

agentagon-0.1.0/.codex-plugin/plugin.json

@@ -0,0 +1,26 @@
+{
+  "name": "ag",
+  "version": "0.1.0",
+  "description": "Review local changes, audit agent applications, and evaluate measured improvements.",
+  "author": {
+    "name": "Agentagon"
+  },
+  "license": "Apache-2.0",
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "Agentagon",
+    "shortDescription": "Review, audit and improve agent applications",
+    "longDescription": "Prepare reviewed benchmarks, audit applications, coordinate bounded improvement experiments in the active host task, inspect task evidence and verified tradeoffs, and clean and reverify selected delivery branches.",
+    "developerName": "Agentagon",
+    "category": "Productivity",
+    "capabilities": [
+      "Read",
+      "Write",
+      "Interactive"
+    ],
+    "defaultPrompt": [
+      "Use ag:review to review my local changes.",
+      "Use ag:audit to audit this agent application."
+    ]
+  }
+}

agentagon-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,27 @@
+---
+name: Bug report
+about: Report a reproducible problem in Agentagon
+---
+
+<!-- For a suspected vulnerability, email security@agentagon.ai instead of opening a public issue. See SECURITY.md. -->
+<!-- Use synthetic or redacted examples. Do not attach credentials, private code/traces, or the full .agentagon directory. -->
+
+## What happened?
+
+Describe the observed behavior and what you expected.
+
+## Reproduction
+
+Provide the smallest command sequence or host request that reproduces the problem, with synthetic inputs when possible.
+
+## Environment
+
+- Agentagon version (`agentagon --version`) and source commit, if known:
+- Installation method (source/virtual environment, installer or wheel):
+- OS and Python version:
+- Coding host and version, if relevant:
+- Workflow and runner (local, SSH or E2B), if relevant:
+
+## Evidence
+
+Include the relevant redacted error output and expected output. Describe coverage limits or skipped checks that affect the result. Remove secrets from configuration examples and use environment-variable names instead of values.

agentagon-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,22 @@
+---
+name: Feature request
+about: Describe a workflow problem or propose an improvement
+---
+
+## Problem
+
+What are you trying to do, and where does the current workflow fall short?
+
+## Proposed behavior
+
+Describe the result you want. Distinguish the proposal from existing behavior.
+
+## Example and alternatives
+
+Give a concrete input/request and expected result. Describe any current workaround or alternatives you considered.
+
+## Constraints and verification
+
+Which workflow, host or runner is affected? Note compatibility, privacy or execution-cost constraints. Explain how a contributor could verify that the change solves the problem.
+
+<!-- Do not include credentials or private code/traces. Report vulnerabilities privately to security@agentagon.ai. -->

agentagon-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,17 @@
+## Problem and result
+
+Describe the previous problem and resulting behavior. Link related issues, if any.
+
+## Evidence
+
+Include a reproduction or usage example when it helps assess the change.
+
+## Validation
+
+List the commands and environments you tested, with results. Identify skipped or unverified integrations separately.
+
+## Compatibility and documentation
+
+Describe configuration, record/contract or packaging changes and any upgrade consequences. Link updated documentation. Omit this section if it does not apply.
+
+<!-- Follow CONTRIBUTING.md. Keep unrelated changes, generated output, .agentagon state and credentials out of the diff. For a suspected vulnerability, report privately to security@agentagon.ai before opening a public PR. -->

agentagon-0.1.0/.github/dependabot.yml

@@ -0,0 +1,12 @@
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5

agentagon-0.1.0/.github/workflows/codeql.yml

@@ -0,0 +1,31 @@
+name: CodeQL
+
+on:
+  push:
+  pull_request:
+  schedule:
+    - cron: '41 6 * * 1'
+
+permissions:
+  contents: read
+
+jobs:
+  analyze:
+    name: CodeQL (${{ matrix.language }})
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      security-events: write
+    strategy:
+      fail-fast: false
+      matrix:
+        language: [python, javascript-typescript]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+      - uses: github/codeql-action/init@b96794f015dfd88f77b49b1c93e0fa7110f94c63 # v4
+        with:
+          languages: ${{ matrix.language }}
+          build-mode: none
+      - uses: github/codeql-action/analyze@b96794f015dfd88f77b49b1c93e0fa7110f94c63 # v4

agentagon-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,95 @@
+name: Website checks and deployment
+
+on:
+  push:
+    paths:
+      - 'website/**'
+      - 'docs/**'
+      - 'docs_theme/**'
+      - 'mkdocs.yml'
+      - 'requirements-docs.txt'
+      - 'THIRD_PARTY_NOTICES.txt'
+      - 'scripts/docs_links.py'
+      - 'scripts/build_site.py'
+      - 'scripts/check_site.py'
+      - 'tests/test_site.py'
+      - '.github/workflows/docs.yml'
+  pull_request:
+    types: [opened, synchronize, reopened, closed]
+    paths:
+      - 'website/**'
+      - 'docs/**'
+      - 'docs_theme/**'
+      - 'mkdocs.yml'
+      - 'requirements-docs.txt'
+      - 'THIRD_PARTY_NOTICES.txt'
+      - 'scripts/docs_links.py'
+      - 'scripts/build_site.py'
+      - 'scripts/check_site.py'
+      - 'tests/test_site.py'
+      - '.github/workflows/docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: website-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    if: github.event.action != 'closed'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
+        with:
+          python-version: '3.13'
+      - uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6
+        with:
+          node-version: '22'
+      - run: python -m pip install -r requirements-docs.txt 'pytest>=8,<10'
+      - name: Build and check website
+        env:
+          IS_PREVIEW: ${{ github.ref != 'refs/heads/main' }}
+        run: |
+          if [ "$IS_PREVIEW" = true ]; then
+            python scripts/build_site.py --preview
+          else
+            python scripts/build_site.py
+          fi
+          node --check website/assets/site.js
+          node --check website/assets/theme-init.js
+          python -m pytest tests/test_site.py --noconftest -q
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: website
+          path: site/
+          retention-days: 7
+      - name: Deploy production or trusted PR preview
+        if: >-
+          (github.event_name == 'push' && github.ref == 'refs/heads/main') ||
+          (github.event_name == 'workflow_dispatch' && github.ref == 'refs/heads/main') ||
+          (github.event_name == 'pull_request' &&
+           github.event.pull_request.head.repo.full_name == github.repository)
+        uses: Azure/static-web-apps-deploy@4d27395796ac319302594769cfe812bd207490b1 # v1
+        with:
+          azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
+          action: upload
+          app_location: site
+          output_location: ''
+          skip_app_build: true
+
+  close-preview:
+    if: >-
+      github.event_name == 'pull_request' && github.event.action == 'closed' &&
+      github.event.pull_request.head.repo.full_name == github.repository
+    runs-on: ubuntu-latest
+    steps:
+      - uses: Azure/static-web-apps-deploy@4d27395796ac319302594769cfe812bd207490b1 # v1
+        with:
+          azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
+          action: close

agentagon-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,143 @@
+name: Release
+
+on:
+  push:
+    tags: ['v*']
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: Existing vX.Y.Z tag to publish or resume
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release-${{ inputs.tag || github.ref_name }}
+  cancel-in-progress: false
+
+env:
+  RELEASE_TAG: ${{ inputs.tag || github.ref_name }}
+  AGENTAGON_TELEMETRY_DISABLED: '1'
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          ref: ${{ env.RELEASE_TAG }}
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
+        with:
+          python-version: '3.13'
+      - name: Require matching versions and successful checks on protected main
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: python scripts/release.py gate --tag "$RELEASE_TAG" --repository "$GITHUB_REPOSITORY"
+      - name: Reuse staged release files when resuming
+        id: reuse
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh api "repos/$GITHUB_REPOSITORY/releases?per_page=100" > "$RUNNER_TEMP/releases.json"
+          if python -c 'import json, os, sys; sys.exit(not any(r["tag_name"] == os.environ["RELEASE_TAG"] for r in json.load(open(sys.argv[1]))))' "$RUNNER_TEMP/releases.json"; then
+            gh release download "$RELEASE_TAG" --repo "$GITHUB_REPOSITORY" --dir dist \
+              --pattern '*.whl' --pattern '*.tar.gz' --pattern SHA256SUMS --pattern RELEASE_NOTES.md
+            python scripts/release.py verify --tag "$RELEASE_TAG"
+            echo 'found=true' >> "$GITHUB_OUTPUT"
+          fi
+      - name: Build and validate one set of distribution files
+        if: steps.reuse.outputs.found != 'true'
+        run: |
+          python -m pip install 'build>=1.2' 'twine>=6,<7' -r requirements-docs.txt
+          python -m build
+          python -m twine check --strict dist/*
+          python scripts/release.py manifest --tag "$RELEASE_TAG"
+          cp "docs/releases/${RELEASE_TAG#v}.md" dist/RELEASE_NOTES.md
+          printf '\nSource revision: `%s`\n' "$(git rev-parse HEAD)" >> dist/RELEASE_NOTES.md
+          python -m venv "$RUNNER_TEMP/release-wheel"
+          "$RUNNER_TEMP/release-wheel/bin/python" -m pip install dist/*.whl
+          cd "$RUNNER_TEMP"
+          "$RUNNER_TEMP/release-wheel/bin/python" "$GITHUB_WORKSPACE/scripts/check_installed.py"
+          "$RUNNER_TEMP/release-wheel/bin/python" "$GITHUB_WORKSPACE/examples/local-audit/demo.py"
+          mkdir release-source
+          tar -xzf "$GITHUB_WORKSPACE/dist/agentagon-${RELEASE_TAG#v}.tar.gz" -C release-source
+          cd "release-source/agentagon-${RELEASE_TAG#v}"
+          python scripts/build_site.py
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: release-packages
+          path: dist/
+          retention-days: 90
+          if-no-files-found: error
+
+  stage:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          ref: ${{ env.RELEASE_TAG }}
+          persist-credentials: false
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
+        with:
+          python-version: '3.13'
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: release-packages
+          path: dist/
+      - name: Preserve reviewed files in a draft GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: python scripts/release.py stage --tag "$RELEASE_TAG" --repository "$GITHUB_REPOSITORY"
+
+  pypi:
+    needs: stage
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/agentagon
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          ref: ${{ env.RELEASE_TAG }}
+          persist-credentials: false
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
+        with:
+          python-version: '3.13'
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: release-packages
+          path: dist/
+      - name: Verify existing PyPI hashes and select only missing files
+        id: pending
+        run: |
+          python scripts/release.py pypi --tag "$RELEASE_TAG"
+          if [ -n "$(ls -A pending)" ]; then echo 'upload=true' >> "$GITHUB_OUTPUT"; fi
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1
+        if: steps.pending.outputs.upload == 'true'
+        with:
+          packages-dir: pending/
+      - name: Verify every published PyPI digest
+        run: |
+          python scripts/release.py pypi --tag "$RELEASE_TAG" --pending verify-published
+          test -z "$(ls -A verify-published)"
+
+  publish:
+    needs: pypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Publish the staged GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release edit "$RELEASE_TAG" --repo "$GITHUB_REPOSITORY" --draft=false --latest

agentagon-0.1.0/.github/workflows/security.yml

@@ -0,0 +1,46 @@
+name: Security checks
+
+on:
+  push:
+  pull_request:
+  schedule:
+    - cron: '23 6 * * 1'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  secrets:
+    name: Secret scan
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Install verified Gitleaks CLI
+        run: |
+          curl --fail --silent --show-error --location --output "$RUNNER_TEMP/gitleaks.tar.gz" \
+            https://github.com/gitleaks/gitleaks/releases/download/v8.30.1/gitleaks_8.30.1_linux_x64.tar.gz
+          echo "551f6fc83ea457d62a0d98237cbad105af8d557003051f41f3e7ca7b3f2470eb  $RUNNER_TEMP/gitleaks.tar.gz" | sha256sum --check
+          tar -xzf "$RUNNER_TEMP/gitleaks.tar.gz" -C "$RUNNER_TEMP" gitleaks
+      - name: Scan history and current files
+        run: |
+          python3 scripts/check_secret_scan.py "$RUNNER_TEMP/gitleaks"
+          "$RUNNER_TEMP/gitleaks" git . --log-opts=--all --redact --no-banner
+          "$RUNNER_TEMP/gitleaks" dir . --redact --no-banner
+
+  dependencies:
+    name: Dependency audit
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
+        with:
+          python-version: '3.13'
+      - run: python -m pip install --upgrade pip
+      - run: python -m pip install '.[dev,browser,e2b]' -r requirements-docs.txt 'pip-audit==2.10.1'
+      - run: python -m pip_audit --local --progress-spinner off

agentagon-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,80 @@
+name: Audit checks
+
+on: [push, pull_request]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        include:
+          - os: ubuntu-latest
+            python-version: '3.12'
+          - os: ubuntu-latest
+            python-version: '3.13'
+          - os: macos-latest
+            python-version: '3.13'
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
+        with:
+          python-version: ${{ matrix.python-version }}
+      - uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6
+        with:
+          node-version: '22'
+      - run: python -m pip install '.[dev]'
+      - run: python -m ruff check src tests skills/eval/helpers scripts examples
+      - run: python -m ruff format --check src tests skills/eval/helpers scripts examples
+      - name: Check shipped JavaScript and shell syntax
+        run: |
+          for script in src/agentagon/dashboard_assets/*.js skills/eval/helpers/*.cjs; do
+            node --check "$script"
+          done
+          sh -n scripts/install.sh
+      - run: python -m pytest -q
+      - run: python -m build
+      - name: Install and exercise the built wheel outside the checkout
+        working-directory: ${{ runner.temp }}
+        run: |
+          python -m venv "$RUNNER_TEMP/agentagon-wheel"
+          "$RUNNER_TEMP/agentagon-wheel/bin/python" -m pip install "$GITHUB_WORKSPACE"/dist/*.whl
+          "$RUNNER_TEMP/agentagon-wheel/bin/python" "$GITHUB_WORKSPACE/scripts/check_installed.py"
+          "$RUNNER_TEMP/agentagon-wheel/bin/python" "$GITHUB_WORKSPACE/examples/local-audit/demo.py"
+
+  browser:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
+        with:
+          python-version: '3.13'
+      - run: python -m pip install '.[dev,browser]'
+      - run: python -m playwright install --with-deps chromium
+      - run: python -m pytest tests/test_dashboard_browser.py -q
+
+  source-package:
+    name: Source package and website
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
+        with:
+          python-version: '3.13'
+      - run: python -m pip install '.[dev]' 'twine>=6,<7' -r requirements-docs.txt
+      - run: python -m build && python -m twine check --strict dist/*
+      - name: Build the website from the extracted source package
+        run: |
+          mkdir "$RUNNER_TEMP/source-package"
+          tar -xzf dist/*.tar.gz -C "$RUNNER_TEMP/source-package"
+          cd "$RUNNER_TEMP"/source-package/agentagon-*
+          python scripts/build_site.py
+          python -m pytest tests/test_site.py --noconftest -q

agentagon-0.1.0/.gitignore

@@ -0,0 +1,23 @@
+.agentagon/
+.venv/
+.venv-docs/
+site/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+*.egg-info/
+build/
+dist/
+.gstack/
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+*.p12
+*.pfx
+id_rsa
+id_ed25519
+.DS_Store
+.worktrees/

agentagon-0.1.0/.gitleaks.toml

@@ -0,0 +1,13 @@
+title = "Agentagon secret scanning"
+[extend]
+useDefault = true
+
+[[rules]]
+id = "generic-api-key"
+
+[[rules.allowlists]]
+description = "Exact public PostHog ingestion token in its shipped default"
+condition = "AND"
+paths = ['''^src/agentagon/usage\.py$''']
+regexTarget = "secret"
+regexes = ['''^phc_CUB2gYkuZX7TsLaJmTxqUg7iCbuitCxkYW4LVgcy9HKn$''']

agentagon-0.1.0/AGENTS.md

@@ -0,0 +1,59 @@
+# Repository guidance
+
+## Authoritative references
+
+| Need | Source |
+|---|---|
+| Setup and contribution workflow | [CONTRIBUTING.md](CONTRIBUTING.md) |
+| Usage and configuration | [README.md](README.md), [user guides](docs/README.md) |
+| Architecture and behavioral boundaries | [Product decisions](docs/contributing/product-decisions.md) |
+| Source and representative tests | [Implementation map](docs/contributing/capabilities.md) |
+| Accepted records and instrumentation | [Versioned contracts](contracts/v1/), [task evidence](docs/task-evidence.md) |
+| Packaging and validation | [pyproject.toml](pyproject.toml), [MANIFEST.in](MANIFEST.in), [CI](.github/workflows/tests.yml), [extended checks](docs/contributing/README.md) |
+
+## Commands
+
+- Use Python 3.12+, Git and Node.js 22 on macOS or Linux; run commands from the repository root with the virtual environment active.
+- Substitute changed Python paths for focused lint/format checks; the table includes the full CI scope.
+
+| Task | Command |
+|---|---|
+| Development setup | `python3 -m venv .venv && . .venv/bin/activate && python -m pip install -e '.[dev]'` |
+| Focused test example | `python -m pytest tests/test_dashboard.py -q` |
+| Full suite | `python -m pytest -q` |
+| Lint | `python -m ruff check src tests skills/eval/helpers scripts examples` |
+| Format check | `python -m ruff format --check src tests skills/eval/helpers scripts examples` |
+| Browser setup and tests | `python -m pip install -e '.[dev,browser]' && python -m playwright install chromium && python -m pytest tests/test_dashboard_browser.py -q` |
+| JavaScript syntax | `for script in src/agentagon/dashboard_assets/*.js skills/eval/helpers/*.cjs; do node --check "$script"; done` |
+| Installer syntax | `sh -n scripts/install.sh` |
+| Build sdist and wheel | `python -m build` |
+
+- Validate packaging changes by installing the built wheel in a fresh environment outside the checkout using the [packaging checks](docs/contributing/README.md#packaging-checks).
+- Local HTTP/browser tests need loopback access; require authorization before enabling [native registration or live SSH/E2B tests](docs/contributing/README.md#optional-integration-checks), and report skips separately from verified results.
+
+## Project boundaries
+
+- Keep model reasoning, candidate edits and independent reviews in the coding-agent host; Python handles evidence, validation and bounded execution.
+- Preserve review scope over captured changes and the fixed audit rubric; full audits may inspect uncommitted or non-Git directories, while evaluation/fix workflows require clean committed inputs.
+- Preserve frozen benchmark comparisons, failed/dominated experiment evidence and user choice among verified alternatives; selection, publication, merge and deployment remain separate actions.
+- Keep dashboard reads within one checkout's display projections; controls remain opt-in with exact-origin/session validation, and reads must not execute work or reconnect to runners.
+- Preserve explicit invocation > project override > user default precedence; store credential references rather than secret values.
+- Optional [Intelligence](docs/intelligence.md) uses separately prepared privacy-safe context/focus; never automatically upload raw code, traces, credentials or the saved audit goal.
+- Keep the remote worker and copyable Python event helper compatible with Python 3.10 and standard-library-only execution.
+
+## Generated files and private state
+
+- Regenerate build output and caches from source; do not commit `.venv/`, `build/`, `dist/`, `*.egg-info/`, `__pycache__/`, `.pytest_cache/` or `.ruff_cache/` (see [.gitignore](.gitignore)).
+- Keep `.agentagon/` private and ignored; use CLI operations for saved state, reports and immutable evidence. Edit prepared host response/templates as workflow inputs, without rewriting frozen records or checksum-addressed artifacts.
+- Treat `contracts/`, `signals/`, `skills/` and `src/agentagon/dashboard_assets/` as shipped source, not disposable generated output; keep packaging declarations and resource references aligned when changing them.
+
+## Documentation and commits
+
+- Lead docs with the decision, outcome or action; use plain words, short paragraphs and concrete examples, without filler or unnecessary qualifiers.
+- Keep each doc focused and each detailed rule in one authoritative place, linking elsewhere instead of duplicating it.
+- Preserve requirements, evidence, tradeoffs and uncertainty; use enough detail to prevent mistakes rather than imposing arbitrary length limits.
+- Distinguish proposals, decisions, implemented behavior and verified results; put dated test counts and environment-specific limits in PR/release records.
+- Preserve unrelated work and history; do not infer authorization to commit, publish, merge or deploy from a documentation workflow.
+- When committing, follow [Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/): one logical change, an imperative summary without a trailing period, and a scope only when useful.
+- Use `feat` for features and `fix` for bugs; other types are allowed. Mark breaking changes with `!` after the type/scope or a `BREAKING CHANGE:` footer.
+- Add a commit body when needed to explain the previous problem, why the change is necessary, and tradeoffs or consequences the diff cannot explain.