From 3973ad53b30a93caa30f16403433bf21da12a908 Mon Sep 17 00:00:00 2001 From: Rahul Vishwakarma Date: Sat, 14 Mar 2026 02:26:38 +0530 Subject: [PATCH 1/2] docs: add WIP markers, alpha banner, ecosystem pages, and plan-to-policy docs - Add announcement bar marking aflock as early alpha with no stable release - Add WIP/active development markers to all doc pages referencing unimplemented features (verification phases 2-6, JWT separation, grants enforcement, gRPC evaluators, keyless signing, sublayout recursion, SO_PEERCRED identity, attestation generation in hooks) - Link each WIP marker to the corresponding GitHub issue (#16-#28) - Add Ecosystem section with Rookery and TestifySec introduction pages - Add plan-to-policy documentation with architecture diagram - Add Discussions link to footer, Star us on GitHub to banner - Add TestifySec and Rookery links to footer - Update homepage feature cards to reflect current implementation status - Add custom CSS for announcement bar matching site theme Co-Authored-By: Claude Opus 4.6 --- docs-website/docusaurus.config.js | 18 ++ docs-website/sidebars.js | 15 ++ .../src/components/HomepageFeatures/index.js | 8 +- docs-website/src/css/custom.css | 34 +++ docs/concepts/attestations.md | 8 + docs/concepts/data-flow.md | 4 + docs/concepts/identity.md | 6 + docs/concepts/policies.md | 8 + docs/concepts/sublayouts.md | 4 + docs/concepts/verification.md | 20 ++ docs/ecosystem/rookery.md | 89 ++++++++ docs/ecosystem/testifysec.md | 30 +++ docs/examples/compliance-evaluation.md | 4 + docs/examples/data-flow-protection.md | 4 + docs/examples/feature-development.md | 4 + docs/plan-to-policy.md | 212 ++++++++++++++++++ docs/reference/comparison.md | 4 + docs/reference/policy-schema.md | 4 + docs/tutorials/claude-code-integration.md | 4 + docs/tutorials/getting-started.md | 18 +- 20 files changed, 487 insertions(+), 11 deletions(-) create mode 100644 docs/ecosystem/rookery.md create mode 100644 docs/ecosystem/testifysec.md create mode 100644 docs/plan-to-policy.md diff --git a/docs-website/docusaurus.config.js b/docs-website/docusaurus.config.js index 17b006e..47c0078 100644 --- a/docs-website/docusaurus.config.js +++ b/docs-website/docusaurus.config.js @@ -47,6 +47,12 @@ const config = { themeConfig: /** @type {import('@docusaurus/preset-classic').ThemeConfig} */ ({ + announcementBar: { + id: 'alpha_notice', + content: + '🚧 Early Alpha Β· aflock has not had a stable release yet and is under active development. Some documented features are still work-in-progress. Open issues Β· Contributions welcome Β· ⭐ Star us on GitHub', + isCloseable: false, + }, image: 'img/aflock-og.png', navbar: { title: 'aflock', @@ -116,6 +122,14 @@ const config = { label: 'Witness', href: 'https://witness.dev', }, + { + label: 'TestifySec', + href: 'https://testifysec.com', + }, + { + label: 'Discussions', + href: 'https://github.com/orgs/aflock-ai/discussions', + }, ], }, { @@ -129,6 +143,10 @@ const config = { label: 'Specification', to: 'docs/docs/reference/policy-schema', }, + { + label: 'Rookery', + href: 'https://github.com/aflock-ai/rookery', + }, ], }, ], diff --git a/docs-website/sidebars.js b/docs-website/sidebars.js index 816abd7..4965f22 100644 --- a/docs-website/sidebars.js +++ b/docs-website/sidebars.js @@ -28,6 +28,11 @@ const sidebars = { }, ], }, + { + type: 'doc', + label: 'Plan-to-Policy', + id: 'docs/plan-to-policy', + }, { type: 'category', label: 'Reference', @@ -48,6 +53,16 @@ const sidebars = { }, ], }, + { + type: 'category', + label: 'Ecosystem', + items: [ + { + type: 'autogenerated', + dirName: 'docs/ecosystem', + }, + ], + }, ], }; diff --git a/docs-website/src/components/HomepageFeatures/index.js b/docs-website/src/components/HomepageFeatures/index.js index 7f7c058..7b59e6b 100644 --- a/docs-website/src/components/HomepageFeatures/index.js +++ b/docs-website/src/components/HomepageFeatures/index.js @@ -16,8 +16,8 @@ const FeatureList = [ title: 'Attest', description: ( <> - Every agent action produces a cryptographically signed in-toto attestation. - The agent never sees the signing key β€” unforgeable proof of compliance. + Agent actions produce cryptographically signed in-toto attestations via DSSE envelopes. + Built on Rookery, a security-hardened attestation framework by TestifySec. ), }, @@ -25,8 +25,8 @@ const FeatureList = [ title: 'Verify', description: ( <> - Verify constraint compliance after the fact with a 6-phase verification algorithm. - Cross-step Rego evaluation, merkle tree ordering proofs, and sublayout recursion. + Verify constraint compliance with a 6-phase verification algorithm. + Signature verification is implemented; identity, Rego, AI evaluation, and sublayout recursion are in active development. ), }, diff --git a/docs-website/src/css/custom.css b/docs-website/src/css/custom.css index 4e90078..2fd24b4 100644 --- a/docs-website/src/css/custom.css +++ b/docs-website/src/css/custom.css @@ -70,3 +70,37 @@ background: url("data:image/svg+xml;charset=utf-8,%3Csvg viewBox='0 0 24 24' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath fill='white' d='M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-.776.417-1.305.76-1.605-2.665-.3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 0 0 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.405 1.02.006 2.04.138 3 .405 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12'/%3E%3C/svg%3E") no-repeat; } + +/* Alpha announcement banner */ +div[class*='announcementBar'] { + background: #f5f3ff !important; + color: #3b0764 !important; + font-size: 0.9rem; + font-weight: 500; + padding: 8px 0; + border-bottom: 1px solid #e9d5ff; +} + +div[class*='announcementBar'] a { + color: #6366f1 !important; + text-decoration: underline; + font-weight: 600; +} + +div[class*='announcementBar'] a:hover { + color: #4338ca !important; +} + +[data-theme='dark'] div[class*='announcementBar'] { + background: #1e1b4b !important; + color: #e0e7ff !important; + border-bottom-color: #312e81; +} + +[data-theme='dark'] div[class*='announcementBar'] a { + color: #a5b4fc !important; +} + +[data-theme='dark'] div[class*='announcementBar'] a:hover { + color: #c7d2fe !important; +} diff --git a/docs/concepts/attestations.md b/docs/concepts/attestations.md index 5910fbf..7530c36 100644 --- a/docs/concepts/attestations.md +++ b/docs/concepts/attestations.md @@ -4,10 +4,16 @@ sidebar_position: 2 # Attestations +:::caution Active Development +Attestation signing using DSSE envelopes is implemented. However, **JWT-based agent authorization** ([#19](https://github.com/aflock-ai/aflock/issues/19)) and the **JWT + Signing Key Separation** model described below are not yet implemented β€” the current implementation has the agent directly holding the signing key. **Attestation generation in hooks mode** is also WIP ([#17](https://github.com/aflock-ai/aflock/issues/17)). Session Merkle trees are designed but not yet implemented. **We're looking for contributors in these areas.** +::: + Every agent action produces a **cryptographically signed attestation** β€” an unforgeable record of what happened. aflock uses the [in-toto](https://in-toto.io/) attestation format wrapped in DSSE envelopes. ## JWT and Signing Key Separation +> **Status: Not yet implemented** β€” Currently the agent directly holds the signing key. See [#19](https://github.com/aflock-ai/aflock/issues/19). + A critical security property is the separation between **authorization** (what the agent is allowed to do) and **attestation** (proof of what the agent did): | Component | Held By | Purpose | @@ -86,6 +92,8 @@ Attestations are wrapped in a Dead Simple Signing Envelope: ## Session Merkle Trees +> **Status: Not yet implemented** β€” Merkle tree construction is designed but no code exists yet. See [#16](https://github.com/aflock-ai/aflock/issues/16). + By constructing a merkle tree over the session JSONL, aflock can cryptographically prove: - **Order**: Turn *n* came after turns 0 through *n-1* diff --git a/docs/concepts/data-flow.md b/docs/concepts/data-flow.md index 3187b05..277ee01 100644 --- a/docs/concepts/data-flow.md +++ b/docs/concepts/data-flow.md @@ -4,6 +4,10 @@ sidebar_position: 5 # Data Flow Tracking +:::info Implementation Status +Data flow classification and flow rule enforcement are implemented in the hooks handler for direct file reads/writes. Note that Bash command analysis currently has a limited set of recognized file-reading commands β€” some commands (e.g., `grep`, `sed`, `awk`) may not trigger data flow checks. See [#25](https://github.com/aflock-ai/aflock/issues/25). +::: + aflock can classify data by sensitivity level and enforce rules preventing data from flowing between classifications. ## Why Data Flow Tracking? diff --git a/docs/concepts/identity.md b/docs/concepts/identity.md index 0cf1f79..fe66652 100644 --- a/docs/concepts/identity.md +++ b/docs/concepts/identity.md @@ -4,12 +4,18 @@ sidebar_position: 1 # Agent Identity +:::caution Active Development +The identity derivation model described here is the target design. The current implementation uses **process-tree heuristics** (`os.Getppid()` and `ps`) rather than kernel-level socket credentials (`SO_PEERCRED`/`LOCAL_PEERCRED`). The MCP server currently uses stdio transport, not Unix domain sockets. See [#24](https://github.com/aflock-ai/aflock/issues/24). The SPIFFE ID format in the implementation also differs from what's documented here. **We're looking for contributors in this area.** +::: + A core insight of aflock is that agent identity should be **derived from introspectable properties** rather than assigned. The agent cannot lie about its identity because the server independently verifies all components. ## Identity Derivation When an agent connects to the aflock server via MCP over a Unix domain socket, the server obtains the connecting process's PID through `SO_PEERCRED` (Linux) or `LOCAL_PEERCRED` (macOS). +> **Current implementation note:** The server currently uses process-tree walking (`os.Getppid()`) over stdio transport rather than socket credentials. See [#24](https://github.com/aflock-ai/aflock/issues/24). + From the PID, the server introspects: | Component | Source | Example | diff --git a/docs/concepts/policies.md b/docs/concepts/policies.md index 666ab92..8ae6386 100644 --- a/docs/concepts/policies.md +++ b/docs/concepts/policies.md @@ -4,6 +4,10 @@ sidebar_position: 0 # Policies +:::info What's Working +Policy loading, signing (`aflock sign`), tool allowlists, file access rules, domain controls, and resource limit enforcement (spend, tokens, turns, time) are all fully implemented. Features marked below as WIP have types/schemas defined but the runtime enforcement code is not yet complete. +::: + An `.aflock` file is a **cryptographically signed policy** that constrains AI agent behavior. Like `package-lock.json` locks dependencies, `.aflock` locks what an agent can do. ## Why Policies? @@ -122,6 +126,8 @@ Follow the principle of least privilege β€” all access denied unless explicitly ## Grants +> **Status: Schema defined, runtime enforcement not yet implemented** β€” The `grants` policy is parsed but never evaluated at runtime. See [#22](https://github.com/aflock-ai/aflock/issues/22). **We're looking for contributors.** + Explicit authorization for resource access: ```json @@ -173,3 +179,5 @@ Define who can sign the policy: ``` Supported types: `publickey`, `keyless` (Sigstore/OIDC), `x509`, `spiffe`. + +> **Note:** `publickey` and `x509` functionaries are implemented. `keyless` (Sigstore) signing is not yet implemented ([#20](https://github.com/aflock-ai/aflock/issues/20)). `spiffe` functionaries work for X509-SVIDs; JWT-SVID support is not yet available. diff --git a/docs/concepts/sublayouts.md b/docs/concepts/sublayouts.md index a57bb48..1ce3f70 100644 --- a/docs/concepts/sublayouts.md +++ b/docs/concepts/sublayouts.md @@ -4,6 +4,10 @@ sidebar_position: 4 # Sublayouts +:::caution Active Development +The sublayout security model is partially implemented. **Numeric limit attenuation** (invariant 1) and **metric accumulation** (invariant 2) work. **Attestation namespacing** (invariant 3), **recursive verification** (invariant 4), the `inherit` field, and constraint enforcement during sub-agent execution are not yet implemented. See [#26](https://github.com/aflock-ai/aflock/issues/26). **We're looking for contributors in this area.** +::: + Inspired by [in-toto sublayouts](https://github.com/in-toto/specification), aflock supports **hierarchical sub-agent delegation** with mandatory constraint attenuation. ## The Problem diff --git a/docs/concepts/verification.md b/docs/concepts/verification.md index 4cbcfe9..64cb387 100644 --- a/docs/concepts/verification.md +++ b/docs/concepts/verification.md @@ -4,6 +4,10 @@ sidebar_position: 3 # Verification +:::caution Active Development +The 6-phase verification pipeline is partially implemented. **Phase 1 (Signature Verification)** works in the `VerifySteps` path. **Phases 2–6** (Identity, Materials Binding, Rego Evaluation, AI Evaluation, Sublayout Recursion) are designed but not yet implemented in code. See [GitHub issue #16](https://github.com/aflock-ai/aflock/issues/16) for progress. **We're looking for contributors in this area.** +::: + aflock's verification algorithm checks that an agent session complied with its policy. Verification proceeds in **six phases** β€” all must pass for the session to be considered compliant. ## The 6-Phase Algorithm @@ -57,22 +61,32 @@ Every attestation must be signed by a key authorized in the policy's `functionar ### Phase 2: Identity Verification +> **Status: Not yet implemented** β€” [#16](https://github.com/aflock-ai/aflock/issues/16) + The agent identity recorded in each attestation must match the policy's `identity` constraints (allowed models, environments, required tools). ### Phase 3: Materials Binding +> **Status: Not yet implemented** β€” no Merkle tree code exists yet. [#16](https://github.com/aflock-ai/aflock/issues/16) + If the policy specifies `materialsFrom.session.merkleTree`, the verifier recomputes the merkle root over the session JSONL and compares it to the root recorded in the final attestation. This proves execution ordering and completeness. ### Phase 4: Constraint Evaluation +> **Status: Not yet implemented** β€” no OPA/Rego integration exists yet. [#16](https://github.com/aflock-ai/aflock/issues/16) + Rego evaluators receive the full set of attestations and can compute cumulative metrics. This is where spend limits, token limits, and custom constraints are checked across all turns. ### Phase 5: AI Evaluation +> **Status: Not yet implemented** β€” [#16](https://github.com/aflock-ai/aflock/issues/16) + AI evaluators assess qualitative properties (code quality, test coverage, task completion) that are difficult to express in formal logic. These are probabilistic β€” critical constraints should use Rego. ### Phase 6: Sublayout Recursion +> **Status: Not yet implemented** β€” [#16](https://github.com/aflock-ai/aflock/issues/16), [#26](https://github.com/aflock-ai/aflock/issues/26) + For each sublayout (sub-agent delegation), verification recurses with the sub-agent's policy and its namespaced attestations. ## Running Verification @@ -94,6 +108,8 @@ Exit code `0` = compliant. Non-zero = violations found with detailed error messa ### Rego Evaluators +> **Status: Schema defined, runtime not yet implemented** β€” [#16](https://github.com/aflock-ai/aflock/issues/16) + Deterministic, cross-step constraint verification: ```json @@ -109,6 +125,8 @@ Deterministic, cross-step constraint verification: ### AI Evaluators +> **Status: Schema defined, runtime not yet implemented** β€” [#16](https://github.com/aflock-ai/aflock/issues/16) + Qualitative assessment: ```json @@ -125,6 +143,8 @@ Qualitative assessment: ### gRPC Evaluators +> **Status: Not yet implemented** β€” [#21](https://github.com/aflock-ai/aflock/issues/21) + Custom evaluation logic: ```json diff --git a/docs/ecosystem/rookery.md b/docs/ecosystem/rookery.md new file mode 100644 index 0000000..412b5a7 --- /dev/null +++ b/docs/ecosystem/rookery.md @@ -0,0 +1,89 @@ +--- +sidebar_position: 0 +--- + +# Rookery + +:::caution Active Development +Rookery is under active development and has not had a stable release yet. The documentation site is being built out β€” more detailed docs will be added soon. If you have questions or want to contribute, join the [discussions](https://github.com/orgs/aflock-ai/discussions). +::: + +[Rookery](https://github.com/aflock-ai/rookery) is a modular attestation framework that aflock builds on for cryptographic evidence generation and verification. It is a security-hardened fork of the [witness](https://witness.dev) project, maintained by [TestifySec](https://testifysec.com). + +## What Rookery Does + +Rookery generates **attestations** β€” cryptographic records that capture what happened during software supply chain activities: + +- **Build provenance**: What was built, by whom, when, and how +- **Source metadata**: Git commit, branch, author information +- **Environment capture**: CI/CD context (GitHub Actions, GitLab CI, AWS CodeBuild) +- **Artifact tracking**: Input materials and output products with digests +- **Security scanning**: Secret detection, SBOM generation + +These attestations are signed using DSSE envelopes and can be verified against policies to ensure supply chain integrity. + +## How aflock Uses Rookery + +aflock uses Rookery's attestation primitives to: + +1. **Sign attestations** in the in-toto format with DSSE envelopes +2. **Verify signatures** against trusted functionaries (public keys, X.509 certificates, SPIFFE SVIDs) +3. **Manage signing keys** including SPIRE-based workload identity + +The `attestation/`, `dsse/`, and `signer/` packages from Rookery provide aflock's cryptographic foundation. + +## Plugin Architecture + +Rookery uses a modular plugin system: + +### Attestors (30+) + +Plugins that generate attestation evidence: + +| Category | Attestors | +|----------|-----------| +| **CI/CD** | GitHub Actions, GitLab CI, AWS CodeBuild, Jenkins | +| **Source** | Git metadata, commit info | +| **Runtime** | Command execution, environment capture | +| **Artifacts** | Material (inputs), Product (outputs) | +| **Security** | Secret scanning (Gitleaks), SBOM | +| **Container** | Docker image info, Kubernetes manifests | +| **Compliance** | SLSA provenance | + +### Signers (8) + +Plugins for cryptographic signing: + +| Signer | Description | +|--------|-------------| +| **File** | Local key-based signing | +| **Fulcio** | Sigstore keyless signing | +| **SPIFFE** | Workload identity signing | +| **Vault** | HashiCorp Vault signing | +| **AWS KMS** | AWS Key Management Service | +| **Azure KMS** | Azure Key Management | +| **GCP KMS** | Google Cloud KMS | +| **Vault Transit** | Vault Transit engine | + +## Security Hardening + +Rookery includes fixes for security issues found in the upstream witness project, including certificate chain validation, symlink path traversal prevention, timestamp authority verification, and KMS offline verification hardening. + +## Getting Started with Rookery + +```bash +git clone https://github.com/aflock-ai/rookery.git +cd rookery +go work sync +make build +``` + +Rookery uses Go workspaces with each plugin as an independent module, allowing you to compose only the attestors and signers you need. + +## Learn More + +- [Rookery on GitHub](https://github.com/aflock-ai/rookery) +- [TestifySec](https://testifysec.com) β€” the company behind witness and rookery +- [witness.dev](https://witness.dev) β€” the upstream project +- [in-toto specification](https://in-toto.io/) β€” the attestation format standard +- [SLSA](https://slsa.dev/) β€” Supply-chain Levels for Software Artifacts diff --git a/docs/ecosystem/testifysec.md b/docs/ecosystem/testifysec.md new file mode 100644 index 0000000..dbe9c94 --- /dev/null +++ b/docs/ecosystem/testifysec.md @@ -0,0 +1,30 @@ +--- +sidebar_position: 1 +--- + +# TestifySec + +[TestifySec](https://testifysec.com) is the company behind aflock and rookery. TestifySec builds tools for software supply chain security, focusing on cryptographic attestation, policy enforcement, and compliance automation. + +## Projects + +| Project | Description | Link | +|---------|-------------|------| +| **aflock** | Cryptographically signed policies for AI agent execution | [GitHub](https://github.com/aflock-ai/aflock) | +| **Rookery** | Modular attestation framework (witness fork) | [GitHub](https://github.com/aflock-ai/rookery) | +| **Witness** | Supply chain attestation and verification | [witness.dev](https://witness.dev) | + +## How the Projects Relate + +| Layer | Project | Role | +|-------|---------|------| +| **Application** | [aflock](https://github.com/aflock-ai/aflock) | AI agent policy enforcement β€” constrains what agents can do | +| **Attestation** | [Rookery](https://github.com/aflock-ai/rookery) | Cryptographic evidence generation β€” signs and verifies attestations | +| **Foundation** | [Witness](https://witness.dev) | Supply chain attestation framework β€” the upstream project Rookery forks | + +**Witness** provides the foundational supply chain attestation framework. **Rookery** is a security-hardened, modular fork with a plugin architecture. **aflock** extends Rookery's attestation primitives to constrain AI agent behavior with signed policies. + +## Contact + +- Website: [testifysec.com](https://testifysec.com) +- Security issues: cole@testifysec.com diff --git a/docs/examples/compliance-evaluation.md b/docs/examples/compliance-evaluation.md index c3f21d8..8eac824 100644 --- a/docs/examples/compliance-evaluation.md +++ b/docs/examples/compliance-evaluation.md @@ -4,6 +4,10 @@ sidebar_position: 1 # Example: Compliance Evaluation +:::info Implementation Status +This example demonstrates the target policy format. **What works now:** tool allowlists, file access rules, resource limits, and identity constraints (model matching). **Not yet implemented:** `grants` enforcement ([#22](https://github.com/aflock-ai/aflock/issues/22)), Rego/AI evaluator execution ([#16](https://github.com/aflock-ai/aflock/issues/16)), and sublayout recursive verification ([#26](https://github.com/aflock-ai/aflock/issues/26)). Sublayout limit attenuation and accumulation work. +::: + A policy for automated OSCAL control assessment with sub-agent delegation. ## Policy diff --git a/docs/examples/data-flow-protection.md b/docs/examples/data-flow-protection.md index 52a1d29..58d6d00 100644 --- a/docs/examples/data-flow-protection.md +++ b/docs/examples/data-flow-protection.md @@ -4,6 +4,10 @@ sidebar_position: 2 # Example: Data Flow Protection +:::info Implementation Status +This example demonstrates the target policy format. **What works now:** data flow classification and flow rules for direct file operations, tool allowlists, file access rules, resource limits. **Known limitation:** Bash file-reading commands beyond the built-in set (cat, head, tail, etc.) are not analyzed for data flow β€” commands like `grep`, `sed`, `awk`, `cp` can bypass flow rules ([#25](https://github.com/aflock-ai/aflock/issues/25)). **SPIFFE functionaries** work for X509-SVIDs but the SPIFFE ID format in the implementation differs from the documented format. +::: + A policy preventing data exfiltration with sensitivity classification. ## Policy diff --git a/docs/examples/feature-development.md b/docs/examples/feature-development.md index 51b55be..6dc880f 100644 --- a/docs/examples/feature-development.md +++ b/docs/examples/feature-development.md @@ -4,6 +4,10 @@ sidebar_position: 0 # Example: Feature Development +:::info Implementation Status +This example demonstrates the target policy format. **What works now:** tool allowlists, file access rules, resource limits (spend, tokens, turns, time), and `requireApproval` patterns. **Not yet implemented:** `requiredAttestations` enforcement, Rego evaluator execution, and AI evaluator execution. These are tracked in [#16](https://github.com/aflock-ai/aflock/issues/16) and [#17](https://github.com/aflock-ai/aflock/issues/17). +::: + A policy for constraining an AI agent implementing features in a todo app. ## Policy diff --git a/docs/plan-to-policy.md b/docs/plan-to-policy.md new file mode 100644 index 0000000..5f8b165 --- /dev/null +++ b/docs/plan-to-policy.md @@ -0,0 +1,212 @@ +# Plan-to-Policy: Spec-Driven Development for AI Agents + +:::info PR Status +Plan-to-policy is implemented on the `spire-attestation-fixes` branch ([PR #11](https://github.com/aflock-ai/aflock/pull/11)) along with SPIRE and MCP fixes. This PR is open and not yet merged to `main`. +::: + +## What It Does + +`plan-to-policy` converts Claude plan files (markdown with acceptance criteria) into `.aflock` policy files with verification steps and AI evaluators. This enables **spec-driven development**: define what the AI must prove it did *before* implementation begins. + +## Why It Matters + +Without plan-to-policy, policies are written manually. With it, the workflow becomes: + +1. Claude creates a plan (in `.claude/plans/` or `~/.claude/plans/`) +2. `aflock plan-to-policy` converts it to a `.aflock` policy +3. Human signs the policy (cryptographic commitment) +4. AI implements the feature, constrained by the policy +5. `aflock verify` confirms all attestations satisfy the policy + +The plan becomes a **verifiable contract** β€” not just documentation. + +## Architecture + +``` + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ plan-to-policy pipeline β”‚ + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ + β”‚ Claude Plan │──────▢ β”‚ Parser │──────▢ β”‚ Generator β”‚ + β”‚ (.md file) β”‚ β”‚ β”‚ β”‚ β”‚ + β”‚ β”‚ β”‚ Extracts steps, β”‚ β”‚ Creates policy β”‚ + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ criteria, files β”‚ β”‚ with evaluatorsβ”‚ + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + ~/.claude/plans/ internal/plan/ β”‚ + plan.md parser.go β”‚ + β”‚ β–Ό + β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ β”‚ β”‚ + └──────────────▢│ .aflock Policy β”‚ + ParsedPlan β”‚ (JSON file) β”‚ + β”‚ β”‚ + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + cmd/aflock/main.go +``` + +*[View interactive diagram on Excalidraw](https://excalidraw.com/#json=8JiDzCXJjIX_MhlU5KSf7,Kq7Xag5CZVcW-N-HVBXwZQ)* + +**Workflow:** Plan β†’ Convert β†’ Sign β†’ Implement β†’ Verify + +### Components + +| Component | File | Purpose | +|-----------|------|---------| +| Parser | `internal/plan/parser.go` | Parses Claude plan markdown into `ParsedPlan` struct | +| Generator | `internal/plan/generator.go` | Converts `ParsedPlan` into `aflock.Policy` | +| CLI Command | `cmd/aflock/main.go` | `aflock plan-to-policy` subcommand | +| Claude Skill | `plugin/skills/plan-to-policy.md` | `/plan-to-policy` skill for Claude Code | + +### Parser Formats + +The parser handles three markdown formats that Claude plans commonly use: + +**Table format** (recommended): +```markdown +## Steps +| Step | Command | AI Evaluator Prompt | +|------|---------|---------------------| +| lint | npm run lint | | +| test | npm test | | +| uat-search | | "PASS if search shows results" | +``` + +**List format**: +```markdown +## Deterministic Steps +- lint: npm run lint +- test: npm test + +## Acceptance Criteria +- Search input is visible on the main page +- Typing a query filters results +``` + +**Section format** (UAT steps): +```markdown +### uat-inbox +**AI Policy Prompt**: PASS if frames show email inbox with list of emails +``` + +### Generator Output + +The generator creates a complete `.aflock` policy with: +- **Steps**: Each plan step becomes a policy step with attestation requirements +- **AI Evaluators**: UAT steps get AI evaluators with PASS/FAIL prompts +- **File Rules**: Optionally inferred from files mentioned in the plan +- **Limits**: Optional default spend/turn limits +- **Tool Rules**: Default set of allowed tools (Read, Edit, Write, Glob, Grep, Bash, LSP) + +## CLI Usage + +```bash +# List available plans +aflock plan-to-policy --list + +# Convert a plan to policy +aflock plan-to-policy \ + --plan ~/.claude/plans/my-plan.md \ + --output .aflock \ + --infer-files \ + --limits + +# Merge new steps into existing policy +aflock plan-to-policy \ + --plan ~/.claude/plans/feature.md \ + --merge + +# Use a different AI model for evaluators +aflock plan-to-policy \ + --plan plan.md \ + --model claude-sonnet-4-6 +``` + +### Flags + +| Flag | Description | Default | +|------|-------------|---------| +| `--plan` | Path to Claude plan markdown file | (required unless --list) | +| `--output` | Output path for policy | `.aflock` | +| `--merge` | Merge into existing policy at output path | `false` | +| `--infer-files` | Generate `files.allow` from plan's referenced files | `false` | +| `--limits` | Add default spend ($10) and turn (50) limits | `false` | +| `--model` | AI evaluator model | `claude-opus-4-5-20251101` | +| `--list` | List available plans in `~/.claude/plans/` | `false` | + +## Generated Policy Example + +Given this plan: +```markdown +# Add Search Feature +## Deterministic Steps +- lint: npm run lint +- test: npm test +## Acceptance Criteria +- Search input is visible on main page +- Typing a query filters results +``` + +Generates this `.aflock` policy: +```json +{ + "version": "1.0", + "name": "add-search-feature", + "steps": { + "lint": { + "name": "lint", + "attestations": [{"type": "https://aflock.ai/attestations/command-run/v0.1"}] + }, + "test": { + "name": "test", + "attestations": [{"type": "https://aflock.ai/attestations/command-run/v0.1"}] + }, + "uat-1": { + "name": "uat-1", + "attestations": [{"type": "https://aflock.ai/attestations/command-run/v0.1"}] + }, + "uat-2": { + "name": "uat-2", + "attestations": [{"type": "https://aflock.ai/attestations/command-run/v0.1"}] + } + }, + "requiredAttestations": ["lint", "test", "uat-1", "uat-2"], + "evaluators": { + "ai": [ + { + "name": "uat-1", + "prompt": "PASS if the following acceptance criterion is met: Search input is visible on main page. FAIL otherwise.", + "model": "claude-opus-4-5-20251101" + }, + { + "name": "uat-2", + "prompt": "PASS if the following acceptance criterion is met: Typing a query filters results. FAIL otherwise.", + "model": "claude-opus-4-5-20251101" + } + ] + }, + "tools": { + "allow": ["Read", "Edit", "Write", "Glob", "Grep", "Bash", "LSP"] + }, + "files": { + "deny": ["**/.env", "**/secrets/**"] + } +} +``` + +## Tests + +```bash +cd /Users/rahulxf/work-dir/aflock +go test ./internal/plan/... +``` + +Tests cover: +- Table, list, and section format parsing +- File path extraction from plan markdown +- Mixed tables (deterministic + UAT in one table) +- Empty content handling +- Real-world plan parsing +- Policy generation (basic, with limits, file inference, merge mode) +- End-to-end (parse markdown β†’ generate policy β†’ verify JSON roundtrip) diff --git a/docs/reference/comparison.md b/docs/reference/comparison.md index b6aba35..285493b 100644 --- a/docs/reference/comparison.md +++ b/docs/reference/comparison.md @@ -52,3 +52,7 @@ aflock is unique in combining: 5. **Cross-step Rego**: Cumulative constraint checking 6. **Sublayouts**: Hierarchical sub-agent delegation 7. **Merkle proofs**: Session ordering and completeness + +:::caution +Some features in the comparison table above reflect the target design. In the current alpha, Rego evaluators, Merkle proofs, full sublayout recursion, and identity verification are not yet implemented at runtime. See the [implementation status](https://github.com/aflock-ai/aflock/issues) for details. +::: diff --git a/docs/reference/policy-schema.md b/docs/reference/policy-schema.md index b37db4d..5cafe6d 100644 --- a/docs/reference/policy-schema.md +++ b/docs/reference/policy-schema.md @@ -4,6 +4,10 @@ sidebar_position: 1 # Policy Schema +:::info Implementation Status +The schema below represents the full target format. Fields that are parsed but **not yet enforced at runtime**: `expires` ([#18](https://github.com/aflock-ai/aflock/issues/18)), `grants` ([#22](https://github.com/aflock-ai/aflock/issues/22)), `evaluators.grpc` ([#21](https://github.com/aflock-ai/aflock/issues/21)), `evaluators.rego` and `evaluators.ai` at verification time ([#16](https://github.com/aflock-ai/aflock/issues/16)), `materialsFrom.session.merkleTree`, and `sublayouts.inherit`/`sublayouts.attestationPrefix` ([#26](https://github.com/aflock-ai/aflock/issues/26)). Functionary type `keyless` (Sigstore) is not yet implemented ([#20](https://github.com/aflock-ai/aflock/issues/20)). +::: + Complete reference for the `.aflock` policy file format. ## Full Schema diff --git a/docs/tutorials/claude-code-integration.md b/docs/tutorials/claude-code-integration.md index af30e50..c77c08a 100644 --- a/docs/tutorials/claude-code-integration.md +++ b/docs/tutorials/claude-code-integration.md @@ -4,6 +4,10 @@ sidebar_position: 1 # Claude Code Integration +:::caution Active Development +Hook-based constraint enforcement (tool allowlists, file access, limits) is working. **Attestation generation in hooks mode** is not yet implemented ([#17](https://github.com/aflock-ai/aflock/issues/17)). The MCP server exposes tools and identity discovery, but note that HTTP mode currently has no authentication ([#27](https://github.com/aflock-ai/aflock/issues/27)) β€” use stdio mode for now. Policy expiration is not yet enforced at runtime ([#18](https://github.com/aflock-ai/aflock/issues/18)). +::: + aflock integrates with Claude Code through two mechanisms: **hooks** and **MCP server**. This tutorial covers both approaches. ## Hook Integration diff --git a/docs/tutorials/getting-started.md b/docs/tutorials/getting-started.md index 593e1ff..7901864 100644 --- a/docs/tutorials/getting-started.md +++ b/docs/tutorials/getting-started.md @@ -4,6 +4,10 @@ sidebar_position: 0 # Getting Started +:::caution Alpha Software +aflock is under active development. Policy creation, signing, hooks integration, and resource limit enforcement are working. The 6-phase verification pipeline is partially implemented (Phase 1 only). See the [open issues](https://github.com/aflock-ai/aflock/issues) for current status. +::: + This tutorial walks you through creating your first `.aflock` policy, integrating it with Claude Code, and verifying agent compliance. ## Prerequisites @@ -120,14 +124,14 @@ After a session completes, verify the attestations: aflock verify --policy .aflock ``` -This runs the 6-phase verification algorithm: +This runs the verification algorithm. Currently Phase 1 (Signature Verification) is implemented. The full 6-phase pipeline is in active development ([#16](https://github.com/aflock-ai/aflock/issues/16)): -1. **Signature Verification** β€” Check cryptographic signatures -2. **Identity Verification** β€” Agent matches policy constraints -3. **Materials Binding** β€” Merkle tree and git hash verification -4. **Constraint Evaluation** β€” Rego policies against all attestations -5. **AI Evaluation** β€” Qualitative assessments -6. **Sublayout Recursion** β€” Verify sub-agent attestations +1. **Signature Verification** β€” Check cryptographic signatures (**implemented**) +2. **Identity Verification** β€” Agent matches policy constraints (*WIP*) +3. **Materials Binding** β€” Merkle tree and git hash verification (*WIP*) +4. **Constraint Evaluation** β€” Rego policies against all attestations (*WIP*) +5. **AI Evaluation** β€” Qualitative assessments (*WIP*) +6. **Sublayout Recursion** β€” Verify sub-agent attestations (*WIP*) Exit code `0` means the session was compliant. Non-zero means violations were found. From 5ae0077416aee639e4e3807b4a92173a306f38ab Mon Sep 17 00:00:00 2001 From: Rahul Vishwakarma Date: Sat, 14 Mar 2026 02:30:05 +0530 Subject: [PATCH 2/2] docs: revert Attest feature card to original text Keep the original copy for the Attest card on the homepage. Co-Authored-By: Claude Opus 4.6 --- docs-website/src/components/HomepageFeatures/index.js | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs-website/src/components/HomepageFeatures/index.js b/docs-website/src/components/HomepageFeatures/index.js index 7b59e6b..424bfd3 100644 --- a/docs-website/src/components/HomepageFeatures/index.js +++ b/docs-website/src/components/HomepageFeatures/index.js @@ -16,8 +16,8 @@ const FeatureList = [ title: 'Attest', description: ( <> - Agent actions produce cryptographically signed in-toto attestations via DSSE envelopes. - Built on Rookery, a security-hardened attestation framework by TestifySec. + Every agent action produces a cryptographically signed in-toto attestation. + The agent never sees the signing key β€” unforgeable proof of compliance. ), },