From 98e0fd0a01a41f192a7205811dd158c2fa7b9e40 Mon Sep 17 00:00:00 2001 From: dgenio Date: Mon, 9 Mar 2026 06:15:01 +0000 Subject: [PATCH 1/2] docs: add agent-facing documentation system Rewrite AGENTS.md with full domain vocabulary, security rules, code conventions, weaver-spec references, and documentation map. Add docs/agent-context/ canonical shared layer: - architecture.md: intent, boundaries, tradeoffs - workflows.md: authoritative commands, PR conventions, doc governance - invariants.md: weaver-spec compliance, forbidden shortcuts, ordering traps - lessons-learned.md: failure-capture workflow, recurring mistakes - review-checklist.md: pre-submit self-check, cross-file consistency Add tool-specific instruction files: - .github/copilot-instructions.md: review-critical projections for Copilot - .claude/CLAUDE.md: Claude-specific operating instructions Update CHANGELOG.md with new documentation entries. --- .claude/CLAUDE.md | 56 +++++++++++ .github/copilot-instructions.md | 53 ++++++++++ AGENTS.md | 133 ++++++++++++++++++++++--- CHANGELOG.md | 4 + docs/agent-context/architecture.md | 50 ++++++++++ docs/agent-context/invariants.md | 76 ++++++++++++++ docs/agent-context/lessons-learned.md | 46 +++++++++ docs/agent-context/review-checklist.md | 63 ++++++++++++ docs/agent-context/workflows.md | 57 +++++++++++ 9 files changed, 524 insertions(+), 14 deletions(-) create mode 100644 .claude/CLAUDE.md create mode 100644 .github/copilot-instructions.md create mode 100644 docs/agent-context/architecture.md create mode 100644 docs/agent-context/invariants.md create mode 100644 docs/agent-context/lessons-learned.md create mode 100644 docs/agent-context/review-checklist.md create mode 100644 docs/agent-context/workflows.md diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md new file mode 100644 index 0000000..66d05b3 --- /dev/null +++ b/.claude/CLAUDE.md @@ -0,0 +1,56 @@ +# Claude Instructions — agent-kernel + +Read `AGENTS.md` before making any changes. It is the canonical source of truth +for all shared rules, conventions, and documentation pointers. + +## Explore before acting + +- Read `AGENTS.md` and the relevant `docs/agent-context/` file for the topic + before proposing changes. +- Check existing code patterns in the target area. Do not infer repo-wide + conventions from a single file. +- When path-specific conventions exist (see Code conventions in `AGENTS.md`), + follow them exactly. + +## Implement safely + +- Preserve invariants. Consult `docs/agent-context/invariants.md` before any + change that touches security, tokens, policy, or the firewall. +- Use only the conventions documented in `AGENTS.md`. Do not invent new ones. +- Use `make ci` as the single validation command. Do not guess alternatives. +- Do not "clean up" or "simplify" code unless the change was requested. Hidden + constraints may exist. + +## Validate before completing + +- Run `make ci` and confirm it passes. +- If a public API, workflow, invariant, or convention changed, update the + relevant canonical doc in the same changeset. +- Verify that every changed docstring matches the final implementation. +- Check for dead code: unused parameters, fixtures, or helpers. + +## Handle contradictions + +When docs contradict code or each other: +1. Code is authoritative over docs. +2. Canonical shared docs (`AGENTS.md`, `docs/agent-context/`) are authoritative + over tool-specific files. +3. Surface the contradiction explicitly. Do not silently pick one side. +4. Fix stale docs in the same changeset when possible. + +## Capture lessons + +When a mistake or unexpected pattern is discovered during work: +1. Determine if it generalizes — would it recur in a similar task? +2. If yes, identify the canonical home using the workflow in + `docs/agent-context/lessons-learned.md`. +3. Treat candidate lessons as provisional. Do not promote a fresh observation + into durable guidance from a single incident. + +## Update order + +1. Update canonical shared docs (`AGENTS.md`, `docs/agent-context/`) first. +2. Update tool-specific files (this file, `.github/copilot-instructions.md`) + second. +3. If a Claude-specific rule becomes shared and durable, promote it into + canonical docs and remove it from `.claude/`. diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..33983c3 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,53 @@ +# Copilot Instructions — agent-kernel + +> Canonical rules: `AGENTS.md`. This file projects review-critical rules that +> must be visible during GitHub PR review. + +## Review checklist + +Flag these in every PR — CI does not catch them: + +- Docstrings and descriptions must match actual implementation. +- No security bypass vectors: whitespace-only justification, truncated JSON, bare `int()` on untrusted input. +- No dead code: unused parameters, fixtures, or helpers. +- No backward-compat breaks: adding required methods to an existing Protocol breaks downstream. +- Naming consistent: use capability, principal, grant, Frame — never synonyms. + +Canonical checklist: `docs/agent-context/review-checklist.md` + +## Code and docs reviewed together + +- PRs that change public APIs, workflows, invariants, review rules, or path conventions must include doc updates. +- If a docstring changed, verify it matches the final code. +- Code is authoritative over docs. Fix stale docs in the same PR. +- Surface contradictions explicitly. Do not silently work around them. + +## Invariants + +Non-negotiable. Violations silently degrade security: + +- Firewall always mediates: `RawResult → Frame`. Never bypass. +- Token verification before every invocation. Never skip. +- Non-admin principals never get `raw` response mode. +- Policy rule ordering is security-critical — a rule placed before sensitivity checks creates a silent bypass. +- New `SensitivityTag` values need a matching policy rule, or the tag is silently ignored. + +Full list: `docs/agent-context/invariants.md` + +## Convention discipline + +- Follow conventions in `AGENTS.md`. Do not invent new ones. +- `make ci` is the single pre-push command. Do not guess alternatives. +- Custom exceptions from `errors.py` only. Never raise bare `ValueError`/`KeyError` to callers (catching stdlib internally to remap is fine). +- No new dependencies without justification. + +## Canonical sources + +| Topic | File | +|-------|------| +| All shared rules | `AGENTS.md` | +| Hard invariants | `docs/agent-context/invariants.md` | +| Full review checklist | `docs/agent-context/review-checklist.md` | +| Workflows & commands | `docs/agent-context/workflows.md` | +| Recurring mistakes | `docs/agent-context/lessons-learned.md` | +| Architecture intent | `docs/agent-context/architecture.md` | diff --git a/AGENTS.md b/AGENTS.md index 589fff4..f3608fc 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,38 +1,143 @@ # AGENTS.md — AI Agent Instructions -This file provides instructions for AI coding agents (Copilot, Cursor, etc.) working in this repository. +This is the canonical source of truth for AI coding agents working in this repository. +Tool-specific instruction files (`.github/copilot-instructions.md`, `.claude/CLAUDE.md`) +reference this file and add only tool-specific guidance. ## Repo layout ``` -src/agent_kernel/ — library source (one module per concern, ≤300 lines each) -tests/ — pytest test suite -examples/ — runnable demos (no internet required) -docs/ — architecture and security documentation +src/agent_kernel/ — library source (one module per concern, ≤300 lines each) + drivers/ — capability drivers (one file per driver) + firewall/ — context firewall (redaction, summarization, budgets) +tests/ — pytest suite (one test file per module) +examples/ — runnable demos (prefer offline; network OK with fallback) +docs/ — reference documentation +docs/agent-context/ — deeper agent guidance (architecture, workflows, invariants) ``` +## Weaver ecosystem + +agent-kernel is part of the **Weaver ecosystem**: +- [weaver-spec](https://github.com/dgenio/weaver-spec) — formal specification with invariants +- [contextweaver](https://github.com/dgenio/contextweaver) — context compilation library +- ChainWeaver — orchestration layer + +This repo must conform to weaver-spec invariants. Key invariants (all equally critical): +- **I-01**: Every tool output must pass through a context boundary before reaching the LLM. +- **I-02**: Context boundaries must enforce budgets (size, depth, field count). +- **I-06**: Tokens must bind principal + capability + constraints; no reuse across principals. + +Full spec: [dgenio/weaver-spec](https://github.com/dgenio/weaver-spec) + +## Domain vocabulary + +Use these terms consistently. Never substitute synonyms: + +| Term | Means | Not | +|------|-------|-----| +| capability | a registered, auditable action | tool, function, API | +| principal | the identity invoking a capability | agent, user, caller | +| grant | a policy-approved token issuance | permission, access | +| Frame | the bounded, redacted result returned to the LLM | response, output | + ## Quality bar -- `make ci` must pass before every commit. +- `make ci` must pass before every commit. It runs: `fmt → lint → type → test → example`. - All public interfaces need type hints and docstrings. -- Use custom exceptions from `errors.py` — never bare `ValueError` or `KeyError`. +- Never raise bare `ValueError` or `KeyError` to callers. Use custom exceptions from `errors.py`. Catching stdlib exceptions internally to remap them is fine. +- Error messages are part of the contract — tests must assert both exception type and message. - Keep modules ≤ 300 lines. Split if needed. -- No randomness in matching, routing, or summarization (deterministic outputs). +- No randomness in matching, routing, or summarization. Deterministic outputs always. +- No new dependencies without justification. The dep list is intentionally minimal (`httpx` only). ## Security rules - Never log or print secret key material. -- HMAC secrets come from `AGENT_KERNEL_SECRET` env var; fall back to a random dev secret with a logged warning. -- Tokens are tamper-evident (HMAC-SHA256) but not encrypted — document this. -- Confused-deputy prevention: tokens bind to `principal_id + capability_id + constraints`. +- HMAC secrets come from `AGENT_KERNEL_SECRET` env var; fallback to a random dev secret with a logged warning. +- Tokens are HMAC-signed but **not encrypted**. Never store secrets in token payloads. +- Confused-deputy prevention: tokens bind `principal_id + capability_id + constraints`. +- Never bypass token verification before capability invocation. +- Firewall always transforms `RawResult → Frame`. Raw driver output never reaches the LLM. +- Non-admin principals never get `raw` response mode. The Firewall downgrades to `summary`. +- No duplicate capability IDs in the registry. + +See [docs/agent-context/invariants.md](docs/agent-context/invariants.md) for the full "never do" list and security traps. + +## Code conventions + +**All modules (`src/agent_kernel/`):** +Relative imports. Dataclasses with `slots=True`. Protocols for interfaces. +`__all__` in every `__init__.py`. Google-style docstrings. +`CamelCase` for classes, `snake_case` for functions. Error classes end with `Error`. + +**Drivers (`drivers/`):** +One file per driver. `Driver` Protocol in `base.py`. Async `execute()` method. +Driver classes end with `Driver`. Use `DriverError` for exceptions. + +**Firewall (`firewall/`):** +Pure functions for redaction and summarization. `Firewall` class in `transform.py` orchestrates. +Use `FirewallError` for exceptions. + +**Tests (`tests/`):** +Every module has a corresponding test file (`kernel.py` → `test_kernel.py`). +Conftest fixtures only for cross-test reuse (≥2 test files). Local helpers otherwise. -## Adding a new capability driver +**Examples (`examples/`):** +Prefer offline. Network examples OK only with a clear fallback. + +## Workflow + +- One logical change per PR. Squash-merge. Conventional commit titles (`feat:`, `fix:`, `test:`, `docs:`). +- `make ci` is the single authoritative pre-push command. +- Update `CHANGELOG.md` in the same PR when adding features or fixes. +- Code is authoritative over docs. Fix stale docs when you spot discrepancies. + +See [docs/agent-context/workflows.md](docs/agent-context/workflows.md) for full details. + +## Adding a capability driver 1. Implement the `Driver` protocol in `src/agent_kernel/drivers/`. 2. Register it with `StaticRouter` or implement a custom `Router`. 3. Add integration tests in `tests/test_drivers.py`. -## Adding a new policy rule +See [docs/integrations.md](docs/integrations.md) for MCP and HTTP examples. + +## Adding a policy rule 1. Add the rule to `DefaultPolicyEngine.evaluate()` in `policy.py`. -2. Cover it with a test in `tests/test_policy.py`. +2. **Placement matters:** rules are evaluated in order. A new rule placed before sensitivity checks silently bypasses them. +3. If adding a new `SensitivityTag`, you must also add a corresponding policy rule — otherwise the tag is silently ignored. +4. Cover it with a test in `tests/test_policy.py`. + +## Review checklist (beyond `make ci`) + +Before submitting a PR, verify: +- [ ] Docstrings and descriptions match the actual implementation. +- [ ] Security edge cases handled (whitespace-only justification, truncated JSON, bare `int()` on untrusted input). +- [ ] No dead or unused code (parameters, fixtures, helpers). +- [ ] No backward compatibility breaks (e.g., adding required methods to a Protocol). +- [ ] Naming consistent across docs and code (use capability, principal, grant, Frame — never synonyms). + +See [docs/agent-context/review-checklist.md](docs/agent-context/review-checklist.md) for the full checklist. + +## Documentation map + +| Topic | Canonical source | +|-------|-----------------| +| Architecture & design intent | [docs/agent-context/architecture.md](docs/agent-context/architecture.md) | +| Components & API reference | [docs/architecture.md](docs/architecture.md) | +| Security model & threats | [docs/security.md](docs/security.md) | +| Hard invariants & forbidden shortcuts | [docs/agent-context/invariants.md](docs/agent-context/invariants.md) | +| Workflow rules & commands | [docs/agent-context/workflows.md](docs/agent-context/workflows.md) | +| Recurring mistakes | [docs/agent-context/lessons-learned.md](docs/agent-context/lessons-learned.md) | +| Review & self-check | [docs/agent-context/review-checklist.md](docs/agent-context/review-checklist.md) | +| Driver integration patterns | [docs/integrations.md](docs/integrations.md) | +| Capability design conventions | [docs/capabilities.md](docs/capabilities.md) | +| Context firewall details | [docs/context_firewall.md](docs/context_firewall.md) | + +## Update policy + +Code is authoritative. When docs contradict code, fix the docs. +Each topic has one canonical source (see table above). Update the canonical source; +do not create parallel guidance elsewhere. diff --git a/CHANGELOG.md b/CHANGELOG.md index 3788a9a..5440996 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,12 +8,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] ### Added +- Agent-facing documentation system: `docs/agent-context/` (architecture, workflows, invariants, lessons-learned, review-checklist). +- `.github/copilot-instructions.md` — review-critical projections for GitHub Copilot. +- `.claude/CLAUDE.md` — Claude-specific operating instructions. - PyPI publish workflow (`.github/workflows/publish.yml`) with Trusted Publisher (OIDC) (#37). - `RELEASE.md` documenting the full release process. - `[project.urls]` in `pyproject.toml` (Homepage, Repository, Documentation, Changelog). - Optional dependency groups: `mcp` and `otel` in `pyproject.toml`. ### Changed +- Rewrote `AGENTS.md` with full domain vocabulary, security rules, code conventions, documentation map, and weaver-spec references. - Renamed PyPI package from `agent-kernel` to `weaver-kernel` to align with Weaver ecosystem. - Added `workflow_call` trigger to CI workflow so publish workflow can reuse it as a gate. diff --git a/docs/agent-context/architecture.md b/docs/agent-context/architecture.md new file mode 100644 index 0000000..1ae5743 --- /dev/null +++ b/docs/agent-context/architecture.md @@ -0,0 +1,50 @@ +# Architecture — Agent Context + +> Canonical source for architectural intent and design tradeoffs. +> For component API details, see [../architecture.md](../architecture.md). +> For hard invariants, see [invariants.md](invariants.md). + +## Intent + +agent-kernel is a **capability-based security kernel** for AI agents operating in large +tool ecosystems (MCP, HTTP APIs, internal services). It sits between the LLM and raw tool +execution, enforcing least-privilege, confused-deputy prevention, and context firewalling. + +The architecture optimizes for: +- **Security over convenience** — every capability invocation requires a scoped, signed token. +- **Bounded LLM context** — the Firewall always transforms raw output into a bounded Frame. +- **Auditability** — every action is traced; no silent execution. +- **Determinism** — no randomness in matching, routing, or summarization. + +## Major boundaries + +1. **Kernel ↔ Drivers**: The Kernel never exposes raw driver output. The Firewall always + mediates. This boundary enforces weaver-spec I-01. + +2. **PolicyEngine ↔ Kernel**: Policy decisions are made *before* token issuance, not at + execution time. The token carries the approved constraints. This prevents + time-of-check/time-of-use gaps. + +3. **TokenProvider ↔ Kernel**: Tokens are verified on every `invoke()`, not just at + issuance. This prevents replayed, expired, or tampered tokens from executing. + +4. **Registry ↔ Router**: The registry owns capability metadata; the router maps + capabilities to drivers. They are deliberately separate so that routing changes + don't affect policy or capability definitions. + +## Key tradeoffs + +| Decision | Why | Consequence | +|----------|-----|-------------| +| Tokens signed, not encrypted | Simplicity; avoids key management complexity | Payloads are readable — never store secrets in them | +| Keyword-based capability search | Deterministic; no external service dependency | Less flexible than semantic search; relies on good tagging | +| Firewall is mandatory | Prevents accidental context blowup and data leakage | All output is bounded; debugging requires admin `raw` mode | +| Single dep (`httpx` only) | Minimal attack surface for a security kernel | Adding a dependency requires justification | + +## Things not to simplify + +- **Do not bypass the Firewall** to "improve performance." It enforces I-01 and I-02. +- **Do not merge PolicyEngine and TokenProvider.** Policy decides; tokens carry the + decision. Merging them creates confused-deputy vulnerabilities. +- **Do not make the Router stateful.** Routing is a pure mapping. Stateful routing + introduces ordering dependencies and non-determinism. diff --git a/docs/agent-context/invariants.md b/docs/agent-context/invariants.md new file mode 100644 index 0000000..3e304a9 --- /dev/null +++ b/docs/agent-context/invariants.md @@ -0,0 +1,76 @@ +# Invariants — Agent Context + +> Canonical source for hard constraints, forbidden shortcuts, and weaver-spec compliance. +> Referenced from `AGENTS.md`. Consult before any change that could weaken security guarantees. + +## Weaver-spec compliance + +agent-kernel must conform to [weaver-spec](https://github.com/dgenio/weaver-spec) invariants. +All three are equally critical — there is no priority ordering. + +| Invariant | Requirement | Where enforced | +|-----------|-------------|----------------| +| **I-01** | Every tool output must pass through a context boundary before reaching the LLM | `Firewall.transform()` in `firewall/transform.py` | +| **I-02** | Context boundaries must enforce budgets (size, depth, field count) | `Budgets` in `firewall/budgets.py` | +| **I-06** | Tokens must bind principal + capability + constraints; no reuse across principals | `HMACTokenProvider.verify()` in `tokens.py` | + +## Forbidden shortcuts — "never do" list + +These constraints are non-negotiable. Violating any one silently degrades security. + +1. **Never bypass the Firewall.** `RawResult → Frame` transformation is mandatory. + Raw driver output must never reach the LLM (except via admin `raw` mode, which + the Firewall itself controls). + +2. **Never skip token verification before invocation.** `Kernel.invoke()` always calls + `verify()` first. Removing or short-circuiting this check defeats confused-deputy + prevention. + +3. **Never allow non-admin principals to get `raw` response mode.** The Firewall + downgrades `raw` to `summary` for non-admin principals. Any code path that bypasses + this check leaks unbounded, unredacted data. + +4. **Never store secrets in token payloads.** Tokens are HMAC-signed but not encrypted. + Payload contents are readable by anyone who holds the token. + +5. **Never log or print secret key material.** The `AGENT_KERNEL_SECRET` and any + derived keys must stay out of logs, error messages, and traces. + +6. **Never add dependencies without justification.** The dependency list is intentionally + minimal (`httpx` only). Every new dependency expands the attack surface. + +7. **Never register duplicate capability IDs.** The registry raises + `CapabilityAlreadyRegistered`. Duplicates cause ambiguous routing and policy + enforcement. + +## Security-critical ordering traps + +These are subtle correctness hazards where the code is correct today but a careless +change introduces a silent bypass. + +### Policy rule ordering +`DefaultPolicyEngine.evaluate()` processes rules sequentially. Adding a new "allow" +rule before sensitivity/justification checks can silently bypass them. Always add +new rules **after** existing sensitivity checks, or verify that the new rule's +position does not short-circuit downstream checks. + +### SensitivityTag coverage +`evaluate()` only checks `SensitivityTag` values it knows about. Adding a new tag to +the `SensitivityTag` enum without a corresponding rule in `evaluate()` means the new +tag is **silently ignored** — capabilities tagged with it pass policy without constraint. + +**Rule:** When adding a `SensitivityTag`, always add a matching policy rule and test. + +## Safe vs. unsafe changes + +| Safe | Unsafe | +|------|--------| +| Refactoring driver internals without changing the `Driver` Protocol | Changing the `Driver` Protocol (breaks downstream implementors) | +| Adding a new response mode to the Firewall | Removing the Firewall step from `invoke()` | +| Adding a new policy rule after existing checks | Adding a policy rule before sensitivity checks | +| Adding error subclasses | Raising bare `ValueError`/`KeyError` to callers | + +## Update triggers for this file +- A weaver-spec invariant is added, changed, or reinterpreted. +- A new "never do" constraint is discovered through review or incident. +- A new security-critical ordering trap is identified. diff --git a/docs/agent-context/lessons-learned.md b/docs/agent-context/lessons-learned.md new file mode 100644 index 0000000..ae3a767 --- /dev/null +++ b/docs/agent-context/lessons-learned.md @@ -0,0 +1,46 @@ +# Lessons Learned — Agent Context + +> Canonical source for recurring mistakes and the process for capturing new lessons. +> This is not an incident archive. Only reusable, generalizable lessons belong here. + +## Failure-capture workflow + +When a mistake is caught in review, CI, or production: + +1. **Determine if it generalizes.** Would this mistake recur if another agent or + contributor faced a similar task? If yes, continue. If it was a one-off, stop. +2. **Write the lesson as a reusable rule.** State the mistake pattern, why it fails, + and the correct approach. Do not write incident narrative. +3. **Assign it one canonical home:** + - Hard invariant → [invariants.md](invariants.md) + - Review check → [review-checklist.md](review-checklist.md) + - Workflow rule → [workflows.md](workflows.md) + - Recurring pattern that doesn't fit above → this file +4. **Update `AGENTS.md`** if the lesson changes a summary rule there. + +## Recurring mistakes + +### Docstring–implementation mismatch +**Pattern:** A docstring or PR description claims behavior that differs from the actual +code. Most frequent finding in historical code reviews. +**Why it recurs:** CI cannot detect semantic mismatches. Docstrings are written at +development time and not updated when behavior changes during implementation. +**Prevention:** Before submitting, re-read every changed docstring and verify it matches +the final implementation. + +### Whitespace-only justification bypass +**Pattern:** Policy requires `justification ≥ 15 chars` for WRITE operations. A string +of 15 spaces satisfies `len()` but conveys no intent. +**Why it fails:** `len()` counts characters, not meaningful content. +**Prevention:** Validate `justification.strip()` length, not raw `len()`. + +### Dead code accumulation +**Pattern:** Parameters, fixtures, or helper functions are added but never used. Linters +catch some but not all cases (e.g., unused test fixtures with `@pytest.fixture`). +**Prevention:** Search for usages of any new parameter, fixture, or helper before +submitting. + +## Update triggers for this file +- A new generalizable mistake pattern is discovered. +- An existing lesson is no longer relevant (remove it). +- A lesson is promoted to a hard rule in another file (move it; don't duplicate). diff --git a/docs/agent-context/review-checklist.md b/docs/agent-context/review-checklist.md new file mode 100644 index 0000000..6f5999d --- /dev/null +++ b/docs/agent-context/review-checklist.md @@ -0,0 +1,63 @@ +# Review Checklist — Agent Context + +> Canonical source for pre-submit self-checks and review gates. +> Use this for both agent self-check and maintainer review. +> For hard invariants, see [invariants.md](invariants.md). +> For workflow rules, see [workflows.md](workflows.md). + +## Pre-submit self-check + +Run before every PR submission. + +### CI gate +- [ ] `make ci` passes (fmt → lint → type → test → example). + +### Correctness +- [ ] Every changed docstring matches the actual implementation. +- [ ] Error messages are tested — tests assert both exception type and message string. +- [ ] Every new module has a corresponding test file. +- [ ] Every new `SensitivityTag` has a matching policy rule in `evaluate()`. + +### Security +- [ ] No secret key material in logs, error messages, or traces. +- [ ] No security edge-case bypass vectors: whitespace-only justification, truncated + JSON passed to `json.loads()`, bare `int()` on untrusted input. +- [ ] Token verification is not skipped or short-circuited. +- [ ] Firewall step is not bypassed — `RawResult → Frame` remains mandatory. +- [ ] No new `raw` response mode paths for non-admin principals. + +### Backward compatibility +- [ ] No new required methods added to an existing Protocol (breaks downstream). +- [ ] If a Protocol must change, consider a separate Protocol or default implementations. + +### Code hygiene +- [ ] No dead or unused code: parameters, fixtures, helpers. +- [ ] Modules stay ≤ 300 lines. +- [ ] Custom exceptions from `errors.py`, not bare `ValueError`/`KeyError` to callers. +- [ ] Domain vocabulary used consistently: capability, principal, grant, Frame. + +### Documentation +- [ ] `CHANGELOG.md` updated (for features and fixes). +- [ ] Naming consistent across docs and code (no mixed terminology). +- [ ] Stale docs fixed if spotted (code is authoritative). + +## Cross-file consistency checks + +When a change touches one of these areas, verify the related files stay aligned: + +| If you change... | Also check... | +|------------------|---------------| +| A Kernel public method | `docs/architecture.md`, `AGENTS.md`, README quickstart | +| Policy rules or `SensitivityTag` | `docs/capabilities.md`, `AGENTS.md` security rules | +| Firewall behavior | `docs/context_firewall.md`, `AGENTS.md` security rules | +| Driver Protocol | `docs/integrations.md`, `AGENTS.md` driver how-to | +| `pyproject.toml` version | `src/agent_kernel/__init__.py` `__version__` | +| Dependency list | `AGENTS.md` (justification required) | +| Error classes | `errors.py` naming convention (must end with `Error`) | +| Review checklist items | `.github/copilot-instructions.md` review checklist | + +## Update triggers for this file +- A new review pattern is identified from PR feedback. +- A lesson from [lessons-learned.md](lessons-learned.md) is promoted to a review check. +- CI gains new checks that make a manual check redundant (remove it). +- The definition of done changes (sync with [workflows.md](workflows.md)). diff --git a/docs/agent-context/workflows.md b/docs/agent-context/workflows.md new file mode 100644 index 0000000..13e1ef8 --- /dev/null +++ b/docs/agent-context/workflows.md @@ -0,0 +1,57 @@ +# Workflows — Agent Context + +> Canonical source for workflow rules, authoritative commands, and documentation governance. +> For the review checklist, see [review-checklist.md](review-checklist.md). + +## Authoritative commands + +| Command | Purpose | When to run | +|---------|---------|-------------| +| `make ci` | Full pre-push gate: fmt → lint → type → test → example | Before every commit | +| `make fmt` | Auto-format with ruff | During development | +| `make lint` | Lint check with ruff | Isolated lint verification | +| `make type` | mypy type check | After changing type annotations | +| `make test` | pytest with coverage | After changing code | +| `make example` | Run all example scripts | After changing examples or core APIs | + +`make ci` is the **single authoritative pre-push command**. It runs all five targets +in sequence. If `make ci` passes, the PR is ready for review. + +**Note:** `make fmt` auto-formats locally, but CI runs `ruff format --check` and fails +on unformatted code. Always run `make ci` to catch this asymmetry. + +## PR conventions + +- One logical change per PR. Do not bundle unrelated changes. +- Squash-merge. Maintain a linear history. +- Conventional commit titles: `feat:`, `fix:`, `test:`, `docs:`, `chore:`, `refactor:`. +- Update `CHANGELOG.md` in the same PR when adding features or fixes. +- Every new module needs a test file (`kernel.py` → `test_kernel.py`). + +## Definition of done + +A PR is ready for merge when: +1. `make ci` passes. +2. The review checklist in [review-checklist.md](review-checklist.md) is satisfied. +3. `CHANGELOG.md` is updated (for features and fixes). +4. No new dependencies without justification. +5. Domain vocabulary is used consistently (see `AGENTS.md`). + +## Documentation governance + +### When docs must be updated +- Adding a feature → update `CHANGELOG.md` + relevant docs. +- Changing a public API → update `docs/architecture.md` and any affected docs. +- Fixing a bug that contradicts documentation → fix the doc in the same PR. +- Discovering a stale doc → fix it. Code is authoritative over docs. + +### How to avoid duplicate authority +- Every durable rule has exactly one canonical home (see Documentation map in `AGENTS.md`). +- Tool-specific instruction files reference `AGENTS.md` and add only tool-specific guidance. +- If you need to reference a rule from another file, use a cross-reference, not a copy. + +### Update triggers for this file +- A new `make` target is added. +- PR conventions change. +- The definition of done changes. +- Documentation governance rules evolve. From 344a417e33e6d96d2c932ede3c0ba72948847bb1 Mon Sep 17 00:00:00 2001 From: dgenio Date: Mon, 9 Mar 2026 06:25:44 +0000 Subject: [PATCH 2/2] docs: standardize make ci timing to pre-push across all files --- AGENTS.md | 2 +- docs/agent-context/workflows.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index f3608fc..c76a774 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -43,7 +43,7 @@ Use these terms consistently. Never substitute synonyms: ## Quality bar -- `make ci` must pass before every commit. It runs: `fmt → lint → type → test → example`. +- `make ci` must pass before every push. It runs: `fmt → lint → type → test → example`. - All public interfaces need type hints and docstrings. - Never raise bare `ValueError` or `KeyError` to callers. Use custom exceptions from `errors.py`. Catching stdlib exceptions internally to remap them is fine. - Error messages are part of the contract — tests must assert both exception type and message. diff --git a/docs/agent-context/workflows.md b/docs/agent-context/workflows.md index 13e1ef8..eb94e68 100644 --- a/docs/agent-context/workflows.md +++ b/docs/agent-context/workflows.md @@ -7,7 +7,7 @@ | Command | Purpose | When to run | |---------|---------|-------------| -| `make ci` | Full pre-push gate: fmt → lint → type → test → example | Before every commit | +| `make ci` | Full pre-push gate: fmt → lint → type → test → example | Before every push | | `make fmt` | Auto-format with ruff | During development | | `make lint` | Lint check with ruff | Isolated lint verification | | `make type` | mypy type check | After changing type annotations |