agent-chief 0.3.1__tar.gz

agent_chief-0.3.1/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,33 @@
+name: 🐛 Bug report
+description: Something behaves wrong
+labels: [bug]
+body:
+  - type: textarea
+    id: what
+    attributes:
+      label: What happened?
+      description: What did you do, what did you expect, what happened instead?
+      placeholder: |
+        1. Sent an event with `curl -X POST ...`
+        2. Expected route "digest", got "interrupt" at 2 AM
+    validations:
+      required: true
+  - type: textarea
+    id: decision
+    attributes:
+      label: The Decision (if routing-related)
+      description: Paste the Decision JSON (route, score, components, reason) — `chief status` or the webhook response.
+      render: json
+  - type: input
+    id: version
+    attributes:
+      label: Version
+      placeholder: "agent-chief 0.1.0 · Python 3.12 · Ubuntu 24.04"
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant log output
+      description: "`~/.chief/audit.log` lines or console output. Redact tokens."
+      render: shell

agent_chief-0.3.1/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: 💬 Question / discussion
+    url: https://github.com/SmileLikeYe/agent-chief/discussions
+    about: Not sure it's a bug? Ask here first — unpolished questions welcome.

agent_chief-0.3.1/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,23 @@
+name: 💡 Feature request
+description: An idea that would make Chief better
+labels: [enhancement]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: The problem
+      description: What attention-management pain does this solve? Start from the pain, not the solution.
+    validations:
+      required: true
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed solution
+      description: How you imagine it working. Sketches and half-ideas welcome.
+  - type: checkboxes
+    id: scope
+    attributes:
+      label: Scope check
+      options:
+        - label: I checked ROADMAP.md — this isn't something v1 deliberately excludes (web UI, cloud sync, Slack/Discord delivery, …)
+          required: true

agent_chief-0.3.1/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,11 @@
+## What & why
+
+<!-- One or two sentences: what changes, and why it's worth changing. -->
+
+## Checklist
+
+- [ ] `make lint test` is green (218+ tests, fully offline)
+- [ ] Behavior changes come with a test that pins them
+- [ ] If a demo event legitimately re-routes: fixture table updated deliberately, reason stated below
+- [ ] Nothing from `SPEC.md §13` (no arbitrary shell, no web UI, no cloud/telemetry, …)
+- [ ] Spec ambiguity resolved? → one-line ADR added to `docs/decisions.md`

agent_chief-0.3.1/.github/workflows/ci.yml

@@ -0,0 +1,16 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - run: uv sync --dev
+      - run: uv run ruff check .
+      - run: uv run pytest

agent_chief-0.3.1/.github/workflows/publish.yml

@@ -0,0 +1,39 @@
+name: Publish to PyPI
+# Trusted Publishing (OIDC) — no API token stored in the repo. One-time setup:
+#   PyPI → project → Publishing → add a GitHub publisher:
+#     owner=SmileLikeYe, repo=agent-chief, workflow=publish.yml, environment=pypi
+# Then: publishing happens automatically when a v* tag's GitHub Release is
+# published, or manually via the Actions tab (workflow_dispatch).
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      repository:
+        description: "testpypi or pypi"
+        default: "pypi"
+permissions:
+  contents: read
+  id-token: write  # required for Trusted Publishing
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - run: uv sync --dev
+      - run: uv run ruff check .
+      - run: uv run pytest
+      - run: uv build
+      # sanity: the exact wheel must run the demo before it reaches an index
+      - run: uvx --from dist/*.whl chief demo --fast
+      - name: Publish
+        run: |
+          if [ "${{ github.event.inputs.repository }}" = "testpypi" ]; then
+            uv publish --publish-url https://test.pypi.org/legacy/
+          else
+            uv publish
+          fi

agent_chief-0.3.1/.github/workflows/release.yml

@@ -0,0 +1,44 @@
+name: Release
+on:
+  push:
+    tags: ["v*"]
+permissions:
+  contents: write
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - run: uv sync --dev
+      - run: uv run ruff check .
+      - run: uv run pytest
+      - run: uv build
+      # the demo must run from the exact wheel being released
+      - run: uvx --from dist/*.whl chief demo --fast
+      - name: Extract this version's CHANGELOG section
+        run: |
+          # literal match (index, not regex) so tags with metachars can't misparse
+          awk -v h="## [${GITHUB_REF_NAME#v}]" '
+            index($0, h) == 1 {hit=1; next}
+            hit && /^## \[/ {exit}
+            hit {print}' CHANGELOG.md > notes.md
+          [ -s notes.md ] || echo "See CHANGELOG.md for details." > notes.md
+      - name: Create or update the GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          # only the changelog's newest version may take the Latest badge —
+          # tagging an old hotfix must not steal it
+          newest=$(grep -oP '^## \[\K[0-9]+\.[0-9]+\.[0-9]+(?=\])' CHANGELOG.md | head -1)
+          latest_flag="--latest=false"
+          [ "$GITHUB_REF_NAME" = "v$newest" ] && latest_flag="--latest"
+          if gh release view "$GITHUB_REF_NAME" >/dev/null 2>&1; then
+            gh release edit "$GITHUB_REF_NAME" --notes-file notes.md "$latest_flag"
+            gh release upload "$GITHUB_REF_NAME" dist/* --clobber
+          else
+            gh release create "$GITHUB_REF_NAME" dist/* \
+              --title "$GITHUB_REF_NAME" --notes-file notes.md "$latest_flag"
+          fi

agent_chief-0.3.1/.github/workflows/sync-release-notes.yml

@@ -0,0 +1,48 @@
+name: Sync release notes
+# Release notes live in CHANGELOG.md; this keeps published GitHub releases in
+# sync with it (and backfills a release for any tag that predates release.yml).
+# Runs only when the changelog (or this file) changes.
+# NOTE: the `## [x.y.z]` heading format is load-bearing — both this workflow
+# and release.yml parse it.
+on:
+  push:
+    branches: [main]
+    paths: ["CHANGELOG.md", ".github/workflows/sync-release-notes.yml"]
+permissions:
+  contents: write
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Upsert a release per changelog version
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          # semver only, anchored to the closing bracket: "[Unreleased]" and
+          # malformed headings never become version tokens; no-match is a no-op
+          versions=$(grep -oP '^## \[\K[0-9]+\.[0-9]+\.[0-9]+(?=\])' CHANGELOG.md || true)
+          for version in $versions; do
+            tag="v$version"
+            # tag existence is a remote fact — never trust the local checkout
+            gh api "repos/${GITHUB_REPOSITORY}/git/ref/tags/$tag" >/dev/null || {
+              echo "no tag $tag on the remote; skipping"; continue; }
+            # literal match (index, not regex) so versions with metachars can't misparse
+            awk -v h="## [$version]" '
+              index($0, h) == 1 {hit=1; next}
+              hit && /^## \[/ {exit}
+              hit {print}' CHANGELOG.md > notes.md
+            # never blank a published release with an empty extraction
+            [ -s notes.md ] || { echo "empty notes for $tag; skipping"; continue; }
+            if gh release view "$tag" >/dev/null 2>&1; then
+              gh release edit "$tag" --notes-file notes.md
+            else
+              gh release create "$tag" --title "$tag" --notes-file notes.md --latest=false
+            fi
+          done
+          # the changelog lists newest first: its first version is Latest —
+          # but only if that release exists yet (changelog may land pre-tag)
+          latest="v$(printf '%s\n' $versions | head -1)"
+          if gh release view "$latest" >/dev/null 2>&1; then
+            gh release edit "$latest" --latest
+          fi

agent_chief-0.3.1/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+dist/

agent_chief-0.3.1/.python-version

@@ -0,0 +1 @@
+3.12

agent_chief-0.3.1/BLOCKERS.md

@@ -0,0 +1,40 @@
+# Blockers & Mocked Steps
+
+Log of steps that needed human-only resources; implemented against mocks/fixtures per goal rule 3.
+
+- Step 8: no live LLM API key (DeepSeek/Anthropic/OpenAI) and no local Ollama on this machine. All four adapters implemented and exercised against recorded HTTP cassettes (httpx.MockTransport); the ≥20/24 demo-agreement test uses cassettes synthesized from the demo fixture's judge blocks, so it validates the wire format + parsing + pipeline, not live model quality. To validate live: `chief init`, pick a backend, rerun tests with a key.
+- Step 9: sentence-transformers/torch cannot be installed on this machine — disk has <1GB free and CPU torch alone needs ~2GB. The `embeddings` extra + SentenceTransformerEmbedder wiring is implemented and the fallback path is tested; all similarity tests run on the deterministic HashEmbedder. To validate the real model: free ~3GB, `uv sync --extra embeddings`, rerun pytest.
+- Step 10: headless dev machine has no notification daemon; DesktopChannel's plyer path is unit-tested with an injected notify_fn and the real path was smoke-tested to degrade gracefully to terminal.
+- Step 11: no Telegram bot token / live chat available. Channel implemented against the Bot HTTP API and integration-tested with an httpx test double (sendMessage payloads, silent flag, inline buttons, callback→feedback rows, mute→POLICY.md). To validate live: create a bot via @BotFather, set [delivery] telegram_token/chat_id, run `chief run`.
+- Step 17: acceptance says "with real embeddings" — blocked by the same disk constraint as Step 9 (torch will not fit). The #5→#19 chain is verified with the deterministic HashEmbedder through MemoryStore/batch_associate; swap in the real model via config once the embeddings extra is installable.
+- Step 20: fresh-machine <10min manual check — verified the local path on this machine: `uv tool install`/`uvx` → `chief init --defaults` (~5s) → `chief run` up with webhook answering in <1 min. A truly fresh machine with a live LLM key could not be exercised tonight (no spare machine/key); the wizard, config, service unit, and run wiring are all covered by tests.
+- Step 22: no local OpenClaw install available. Integration is file-protocol based (tasks/ inbox, outbox/ pickup) and fully covered by tests against a faked OpenClaw home; the manual transcript in docs/openclaw-manual-test.md documents the faked run and what a live run would change.
+- Step 23: "clean machine" quickstart verified on this machine via isolated uvx (1.8s to demo end, well under 60s); a literally separate machine wasn't available tonight.
+- Step 24: publishing to (test) PyPI needs an account token only a human can provide. Everything short of upload is done and verified: `make release-check` runs the demo from the built wheel via isolated uvx (the exact `uvx agent-chief demo` code path), the GIF is reproducible via `make demo-gif`, and v0.1.0 is tagged. To finish: `uv publish --index testpypi` with a token, then re-verify.
+
+## Step 25/27 · Real-backend eval + prompt compare (v3.1)
+- Status: harness complete and CI-gated with the fixtures backend and offline
+  doubles; the CAPABILITY agreement number and prompt-compare diffs against a
+  REAL backend need an LLM API key (or a local Ollama pull).
+- Un-mock: `chief eval --backend deepseek` (or ollama/anthropic/openai) with
+  `[llm].api_key` set in ~/.chief/config.toml; for prompt changes,
+  `chief eval --compare v1 v2 --backend deepseek` and attach the report per
+  CONTRIBUTING.md.
+
+## Step 29 · Dual skill packaging — live-host halves (v3.1)
+- Status: both SKILL.md files lint clean; `chief lite` transcripts in
+  docs/skill-manual-tests.md are real output. The live halves need hosts this
+  machine doesn't have: a local OpenClaw install (see Step 22 entry) and a
+  Claude Code session with the skill loaded and API credentials.
+- Un-mock: copy skills/claude-code/ into a project's .claude/skills/, run a
+  watcher that finds something, verify the agent calls `chief lite` and obeys
+  the route; for OpenClaw follow docs/openclaw-manual-test.md.
+
+## Step 34 · Composio connector — live verification (v3.2)
+- Status: adapter complete against Composio's documented v3 envelope +
+  svix-style HMAC signatures; verified with signed fixtures (GitHub PR,
+  Gmail, Slack triggers). A live round-trip needs a composio.dev account,
+  a webhook subscription pointed at this machine (tunnel), and its secret.
+- Un-mock: `chief connect composio --secret <whsec_...>`, subscribe
+  triggers in the Composio dashboard to https://<tunnel>/v1/connectors/composio,
+  fire a test trigger, watch `chief ui` History.

agent_chief-0.3.1/CHANGELOG.md

@@ -0,0 +1,120 @@
+# Changelog
+
+All notable changes to Chief are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow
+[SemVer](https://semver.org) (0.x: minor bumps may break).
+
+## [0.3.1] — 2026-07-06
+
+Security & robustness hardening of the v0.3.0 product surface (from a
+dedicated multi-agent review pass).
+
+### Fixed
+- **Console XSS → token theft** closed: event/task ids (attacker-shaped) now
+  ride escaped `data-*` attributes with delegated listeners, never inline
+  handlers.
+- All API auth uses constant-time comparison (`hmac.compare_digest`); uvicorn
+  binds `127.0.0.1` explicitly on both servers.
+- **Composio webhook**: timestamp freshness (±5 min anti-replay), 1 MiB body
+  cap before buffering, non-ASCII signature headers no longer 500, non-dict
+  trigger data wrapped instead of crashing.
+- Console task-approve honors `task.executor` (was hardcoded `claude_code` — an
+  escalation over the query-only shell executor).
+- History search runs in SQL, so matches beyond the newest rows are found.
+- One `apply_feedback` path behind HTTP/MCP/Telegram/console: the natural
+  should/shouldn't-interrupt signals now learn identically everywhere (MCP and
+  Telegram previously only stored a raw row); unknown signals are rejected.
+- `chief connect` backs up and refuses to rewrite configs its serializer can't
+  round-trip, instead of corrupting them in place.
+
+## [0.3.0] — 2026-07-06
+
+The "product surface" release (SPEC v3.2, Steps 32–36): Chief for people, not
+just for people who read specs.
+
+### Added
+- **Local web console** (`chief ui`, also served by `chief run`) at
+  `127.0.0.1:8787/ui`: Today / History / Rules / Tasks / Sources views,
+  POLICY.md editing that takes effect immediately, dispatch approve/reject
+  (verification still enforced), and 👍/👎 on every decision. Single user,
+  token-gated, one static HTML file — no cloud, no build toolchain.
+- **Natural feedback**: `should_interrupt` / `should_not_interrupt` as
+  first-class signals — stronger than every inferred signal — via the console,
+  `POST /v1/feedback`, the MCP `feedback` tool, and new Telegram buttons.
+- **Connector framework** with **Composio** as the flagship adapter:
+  HMAC-verified trigger webhooks (`/v1/connectors/composio`) translate
+  GitHub/Gmail/Slack/500+ app events into candidate events; documented slots
+  for zapier/n8n and MCP-push agents.
+- **One-click connect**: `chief connect composio|github|rss` edits config
+  surgically and prints exact next steps; `chief sources` shows status.
+- SPEC §13 revised by the owner: local-only console and connector ingest are
+  in scope; the hosted-UI and chat-delivery bans stand.
+
+## [0.2.0] — 2026-07-05
+
+The "trust & distribution" release (SPEC v3.1, Steps 25–31) plus two
+multi-agent review hardening passes.
+
+### Added
+- **Eval harness** (`chief eval`): a 200-case golden dataset with strictly
+  separated CAPABILITY (improvable, report the number) and REGRESSION evals
+  (the demo 24 — 100% forever, CI-gated); bucketed markdown reports by
+  route/topic/scene.
+- **Decision tracing + cost accounting** (`chief trace <event_id>`): per-stage
+  latency, tokens in/out/cached, and USD cost on every decision, with
+  per-model list prices (DeepSeek cache-hit vs cache-miss modeled explicitly).
+  The Tact Report gained a cost dimension: % events reaching the LLM, cache
+  hit rate, judgment spend — all windowed to the report period.
+- **Prompt governance**: all prompts are versioned Jinja2 templates
+  (`judge/templates/v1/`); the version is stamped into every judged decision's
+  audit record, and `chief eval --compare v1 v2` produces an agreement-delta +
+  flipped-samples diff. House rule: no prompt change merges without one.
+- **Graceful degradation**: chaos-tested judge failures (malformed JSON,
+  timeout, backend down) fall back to rules-only conservative routing — never
+  interrupt while blind, never drop — marked `degraded=true`, auto-recovering,
+  and surfaced in `chief status`.
+- **`chief lite`**: zero-daemon judgment-only mode (stages 1–3 + routing) for
+  one-shot callers and skills.
+- **Dual skill packaging**: Claude Code skill alongside the OpenClaw skill.
+- **Integration examples** (`examples/integrations/`): a stock-analysis-bot
+  feed and a generic webhook template, both runnable offline.
+- **Quantified README**: the first screen leads with numbers regenerated from
+  the deterministic demo replay via `make readme-metrics`, gated by tests.
+- Open-source scaffolding: LICENSE (MIT), CONTRIBUTING, CODE_OF_CONDUCT,
+  SECURITY, issue/PR templates, examples/, bilingual README, `chief --version`.
+
+### Fixed (highlights from the two review passes)
+- Cost accounting: per-model pricing (default gpt-4o-mini configs were billed
+  at gpt-4o rates, ~17×); failed retries and mid-retry transport errors are
+  billed; a single `Decision.cost` source of truth.
+- Robustness: `"usage": null` from OpenAI-compatible proxies no longer breaks
+  judgments; the Brain's outer judge timeout (150s) now fits HTTPJudge's full
+  retry budget; unknown `prompt_version` fails fast at startup; LLM-echoed
+  `usage` keys are stripped before validation.
+- Reserved-namespace hardening: the degradation marker moved to a dedicated
+  `meta` table and externally supplied dunder topics are namespaced at ingest.
+- Eval integrity: regression gates before the paid capability run; a broken
+  fixture fails loud while a flaky backend degrades a single case instead of
+  aborting a paid run; loud warning when "low agreement" is really an outage.
+
+## [0.1.0] — 2026-07-04
+
+Initial release: the full SPEC v3 implementation (Steps 1–24).
+
+- Three-stage worthiness engine (hard rules → similarity classifier → LLM
+  judge: ollama/deepseek/anthropic/openai, all optional) × scene engine with
+  per-scene interrupt thresholds.
+- Five routes: interrupt / digest / dispatch / curate / drop; dispatch
+  verifies results before reporting ("done is a claim, not a proof") and
+  arrives with a plan.
+- Shadow mode (trust is earned), Tact Report, EMA learner with nightly
+  human-readable POLICY.md distillation.
+- Ingest protocol: webhook + MCP tools + GitHub/RSS pollers; delivery over
+  terminal/desktop/Telegram with feedback buttons.
+- Fully offline deterministic demo (`uvx agent-chief demo`) with a
+  full-table routing regression.
+
+[0.3.1]: https://github.com/SmileLikeYe/agent-chief/compare/v0.3.0...v0.3.1
+[0.3.0]: https://github.com/SmileLikeYe/agent-chief/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/SmileLikeYe/agent-chief/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/SmileLikeYe/agent-chief/releases/tag/v0.1.0

agent_chief-0.3.1/CLAUDE.md

@@ -0,0 +1,71 @@
+# CLAUDE.md
+
+Chief — a local-first "chief of staff" that triages everything competing for
+the user's attention (agents, heartbeats, CI, RSS) into exactly one of:
+interrupt / digest / dispatch / curate / drop. Spec: `SPEC.md` (§ references
+throughout the code point there). Build log: `PROGRESS.md`.
+
+## Commands
+
+```bash
+make test           # uv run pytest (313 tests, offline, no keys needed)
+make lint           # uv run ruff check .
+make demo           # offline day-of-engineer replay (deterministic)
+make readme-metrics # regenerate the quantified README first screen
+make release-check  # lint + test + build wheel + run demo from the wheel via uvx
+uv run pytest tests/test_routing.py -k name   # single test
+uv run chief eval   # regression (demo 24, must be 100%) + capability (golden 200)
+uv run chief trace <event_id>   # replay one decision chain with costs
+uv run chief lite '<event json>'  # zero-daemon judgment (skills use this)
+uv run chief ui                   # local web console at 127.0.0.1:8787/ui
+uv run chief connect composio --secret …   # + github / rss; chief sources
+uv run chief eval --learning      # preference-learning reward-loop eval
+```
+
+Everything runs through `uv`. Python 3.12. No network, no API keys, and no
+real `~/.chief` are needed for the test suite — tests set `CHIEF_HOME` to a
+tmpdir and use the `fixtures` judge backend.
+
+## Architecture (one paragraph)
+
+`ingest/` normalizes payloads (webhook :8787, MCP tools, GitHub/RSS pollers) →
+`core/brain.py::Brain.process` runs the pipeline: triage-merge → stage-1 hard
+rules (`core/scorer.py::stage1`) → stage-2 similarity classifier → memory
+associate → LLM judge (`judge/`, pluggable via `judge/factory.py`) →
+`score_and_route` (score = Σ w_topic·component, per-scene thresholds from
+`context/infer.py::SCENE_POLICY`) → persist to SQLite (`core/state.py`, all
+tables use a JSON `data` blob column) → fire-and-forget actor
+(`cli/runtime.py::make_actor`) delivers or dispatches. Dispatch always
+"arrives with a plan": executor runs first, result is verified
+(`dispatch/acceptance.py` — "done is a claim, not a proof"), then delivery.
+Learning: `core/learner.py` (EMA topic weights, shadow mode, nightly
+threshold tuning at 03:00 via the scheduler in `cli/runtime.py`).
+v3.1 additions: `eval/` (golden 200-case dataset + agreement harness),
+`Decision.trace` (per-stage latency/tokens/USD via `judge/pricing.py`),
+versioned prompts (`judge/templates/<v>/*.j2`), and judge-failure degradation
+(rules-only conservative routing, `degraded=true`, auto-recovery).
+
+## Conventions
+
+- Tests first: each `tests/test_*.py` encodes the SPEC §9 acceptance criteria
+  for its step. The demo routing table is a full-table regression
+  (`tests/test_demo_routing.py`) — if you change routing behavior on purpose,
+  update the fixture table deliberately, never loosen the test.
+- Ambiguity in the spec → pick the simpler option and add a one-line ADR to
+  `docs/decisions.md`.
+- `SPEC.md §13` is a hard forbidden list: no arbitrary shell execution
+  (`dispatch/executor.py` shell templates are a query-only argv whitelist —
+  keep it that way, never `shell=True`), no mic/screen/geofencing, no web UI,
+  no cloud sync, no Slack/Discord/WeChat delivery.
+- Embeddings default to the dependency-free `HashEmbedder`
+  (`core/embedding.py`); sentence-transformers is an optional extra
+  (`--extra embeddings`) — never make it a hard import.
+- Human-only resources (LLM keys, Telegram token, PyPI creds) are mocked;
+  status and un-mock instructions live in `BLOCKERS.md`.
+- Prompts are versioned template dirs; no prompt change without a
+  `chief eval --compare` diff report (CONTRIBUTING.md).
+- Release flow: bump pyproject version + add a CHANGELOG.md entry + push a
+  `v*` tag; workflows do the rest. The `## [x.y.z]` changelog heading format
+  is load-bearing — release.yml and sync-release-notes.yml parse it.
+- Commit style: `feat(scope): ...` / `fix:` / `docs:` / `review(phaseN): ...`;
+  ruff + pytest green on every commit.

agent_chief-0.3.1/CODE_OF_CONDUCT.md

@@ -0,0 +1,39 @@
+# Code of Conduct
+
+## Our pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Focusing on what is best for the overall community
+
+Examples of unacceptable behavior:
+
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the maintainers via GitHub issues or the contact listed in
+[SECURITY.md](SECURITY.md). All complaints will be reviewed and investigated
+promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the
+[Contributor Covenant](https://www.contributor-covenant.org), version 2.1.

agent_chief-0.3.1/CONTRIBUTING.md

@@ -0,0 +1,67 @@
+# Contributing to Chief
+
+Thanks for your interest! Chief is small on purpose — the whole brain fits in
+your head after an afternoon of reading. This document gets you productive in
+five minutes.
+
+## Dev setup
+
+```bash
+git clone https://github.com/SmileLikeYe/agent-chief && cd agent-chief
+uv sync --dev          # Python 3.12+, https://docs.astral.sh/uv/
+make test lint         # 218 tests + ruff, fully offline — no keys needed
+make demo              # the offline day-of-engineer replay
+```
+
+The test suite needs **no network, no API keys, and no real `~/.chief`** —
+tests point `CHIEF_HOME` at a tmpdir and use the deterministic `fixtures`
+judge. If your change needs a key to test, it's designed wrong; add a cassette
+(see `judge/fixtures.py` and the httpx MockTransport tests).
+
+## The rules of the house
+
+1. **Tests first.** Every behavior change lands with the test that pins it.
+   The demo routing table (`tests/test_demo_routing.py`) is a full-table
+   regression — if your change legitimately re-routes a demo event, update the
+   fixture table deliberately and say why in the PR; never loosen the test.
+2. **`SPEC.md §13` is a hard no.** No arbitrary shell execution (the shell
+   executor is a query-only argv whitelist — never `shell=True`), no
+   mic/screen/geofencing, no web UI, no cloud sync, no telemetry.
+3. **Ambiguity → simpler option + a one-line ADR** in
+   [`docs/decisions.md`](docs/decisions.md).
+4. **No prompt change merges without an eval diff report.** Prompts are
+   versioned Jinja2 templates under `judge/templates/<version>/`. To change
+   one: copy the current version dir to a new version, edit there, run
+   `chief eval --compare <old> <new>` against a real backend, and attach the
+   generated `eval/reports/compare-*.md` (agreement delta + flipped samples)
+   to the PR.
+5. **Keep the core dependency-light.** Embeddings default to the
+   dependency-free `HashEmbedder`; heavyweight deps go behind optional extras.
+6. **Green on every commit**: `make lint test` must pass.
+
+## Commit style
+
+```
+feat(scope): add per-topic dispatch propensity
+fix: telegram poller surfaces HTTP errors
+docs: clarify quiet-hours semantics
+```
+
+## Pull requests
+
+- One logical change per PR; small is beautiful.
+- Explain *why* in the description; the diff explains *what*.
+- CI (ruff + pytest on 3.12) must be green.
+
+## Good first areas
+
+- New **scene providers** (`context/providers/`) — e.g. OS focus/lock state.
+- New **judge backends** (`judge/`) — subclass the HTTP judge, ~40 lines.
+- New **ingest sources** (`ingest/sources/`) — subclass `Poller`, ~60 lines.
+- New **delivery channels** (`delivery/`) — but check `ROADMAP.md` first;
+  Slack/Discord/WeChat are deliberately v2.
+
+## Questions
+
+Open a [discussion or issue](https://github.com/SmileLikeYe/agent-chief/issues)
+— unpolished questions welcome.

agent_chief-0.3.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SmileLikeYe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agent_chief-0.3.1/Makefile

@@ -0,0 +1,29 @@
+.PHONY: test lint demo demo-gif showcase clean-dist build release-check readme-metrics
+
+test:
+	uv run pytest
+
+lint:
+	uv run ruff check .
+
+demo:
+	uv run chief demo
+
+readme-metrics:
+	uv run python scripts/readme_metrics.py --write
+
+demo-gif:
+	bash scripts/demo-gif.sh
+
+showcase:
+	bash scripts/showcase.sh
+
+clean-dist:
+	rm -f dist/*
+
+build: clean-dist
+	uv build
+
+release-check: lint test build
+	uvx --isolated --from dist/agent_chief-*-py3-none-any.whl chief demo --fast > /dev/null
+	@echo "release check passed"