Integrate canonical v0.1.0 (#2)

Author: afogel

.gitignore

@@ -1,4 +1,6 @@
 .idea/
 .git/
 book/
+site/
+references/
 .DS_Store

SPEC_REVIEW_PRINCIPLES.md

@@ -0,0 +1,71 @@
+# ACS Spec Review Principles
+
+These are the standing judgment calls behind ACS spec decisions. Load this into a coding agent's context when designing, reviewing, or critiquing changes to the schema, hooks, events, or written specification. It pairs with `STYLE.md`: STYLE governs how we write prose, this governs how we decide what goes in the spec.
+
+Each principle is a heuristic, a smell test, and a worked example from a real v0.1.0 decision. Apply them; don't recite them.
+
+## 1. Normative statements live at the altitude of their scope
+
+A `MUST` belongs wherever its truth holds, not wherever it was first written.
+
+- **Cross-cutting invariant** (true across pillars) → define it once, above the pillars, tagged NORMATIVE. *e.g. "`Intent.parsed` MUST NOT be modified by the LLM or by data crossing an untrusted channel."* Intent flows through all three pillars (Instrument fires decisions against it, Trace records it, Inspect catalogs what it authorized), so the invariant lives above them.
+- **Mechanism requirement** (true within one pillar's enforcement) → keep it in that pillar. *e.g. "the Guardian MUST verify approver identity," "a client declaring `provenance_producer: none` MUST be refused at handshake."*
+
+**Smell test:** if a requirement is restated in two pillars, or buried in one pillar but relied on by another, it's at the wrong altitude. Hoist the invariant; leave the mechanics.
+
+## 2. Every wire decision balances six constituencies
+
+A change that optimizes one constituency at the others' expense is suspect. Name the trade before deciding.
+
+1. **Expressiveness**: can the spec describe the real governance situation at all?
+2. **Framework implementers**: can they reach conformance cheaply? This guards the adoption floor.
+3. **Vendors and competitors**: is there room to build differentiated solutions on top? Don't absorb the value vendors should compete on.
+4. **Adopters and deployments**: is integration cost low?
+5. **Wire minimalism**: expressive enough *without* premature functionality or contract bloat that ossifies around guesses.
+6. **Security reality**: does it match where boundary crossing and trust-laundering actually occur?
+
+**Smell test:** "more fields" or "more guidance" usually pays constituency 1 by taxing 2, 3, and 5. If you can't name who you're taxing, you haven't finished the analysis.
+
+## 3. Put it on the wire only if it's lost otherwise
+
+This operationalizes Principle 2. A field earns a place in the contract only if it does one of two things:
+
+- **(a)** captures information lost or unreconstructable downstream, or
+- **(b)** marks a real trust-boundary crossing.
+
+Everything else belongs in `policy_data`, a conformance profile, or vendor territory.
+
+- **On the wire:** provenance that must travel across summarization, memory writes, and agent hops. Drop it and trust launders silently and unrecoverably.
+- **Not on the wire:** risk category, data classification, retention period, control mapping. These are reconstructable from policy plus logs; forcing them into the contract raises the floor (2.2) and commoditizes vendor value (2.3).
+
+**Smell test:** "could a deployment reconstruct this after the fact from what it already logs?" If yes, keep it off the wire.
+
+## 4. The wire is paradigm-neutral; new paradigms ride existing elements first
+
+We name four control paradigms today (IBAC, FIDES, CaMeL, AARM) but these are points on a wider space. They represent different philosophical approaches to crafting effective controls, each grounded in existing standards and research. Others will need support over time, and the contract must accommodate them without being re-cut for each one.
+
+The wire stays neutral. A new paradigm reaches the wire through the elements that already carry paradigm-specific intent:
+
+- `reason_codes`: free vocabulary for machine-readable categorization.
+- `policy_data`: free-form payload, conventionally keyed by paradigm name (`{"ibac": {...}, "fides": {...}}`).
+- `policy_references`: one entry per paradigm when several reject the same action.
+- conformance profiles: when a paradigm needs a declarable capability tier.
+
+A new paradigm earns a wire `MUST` only when it needs a signal none of these can already carry. That is Principle 3 applied to paradigms: if the needed information is expressible through existing conformant elements, it is not a spec change. It is a deployment or profile.
+
+**Smell test:** "does this paradigm need a new wire field, or can it ride `policy_data`, `reason_codes`, or a profile?" If the latter, leave the wire alone. Prefer grounding the paradigm in an existing standard over inventing new surface.
+
+## 5. Normative by default; mark the exceptions
+
+Spec text is normative unless it says otherwise. Mark informative sections explicitly with "This section is non-normative", and treat examples and notes as informative by convention.
+
+- **Non-normative prose carries no RFC 2119 keywords.** A capitalized MUST/SHOULD/MAY in informative text either creates an accidental requirement or teaches readers to ignore the keyword. Lowercase the word, or move the requirement to a normative section.
+- **On a mixed page** (a concept page holding invariants and teaching together), tag each invariant **(normative)** and let the surrounding prose read as informative and keyword-free.
+
+This is the companion to Principle 1. That one fixes *where* a normative statement lives; this one fixes *how its force is marked*. Together they keep a hoisted invariant binding and keep explanatory prose from binding by accident.
+
+**Smell test:** "Is this `MUST` sitting in text a reader would take as binding?" If the section is informative, either the requirement is in the wrong place (hoist it per Principle 1), or the keyword should not be capitalized. Convention follows W3C: default-normative, with informative sections marked explicitly.
+
+---
+
+*This file is meant to grow. Add a numbered section when a recurring judgment call earns the status of a principle.*

docs/acs.md

@@ -1,21 +1,21 @@
 # Agent Control Standard
 
-The Agent Control Standard (ACS) provides specification for building [trustworthy agents](./README.md).
-Agents that implement ACS can be deployed with higher trust.
-They are instrumentable, traceable and inspectable.
-They are an open book 
+The Agent Control Standard (ACS) is a wire-format specification that lets a separate **Guardian Agent** permit, deny, or modify what an AI agent does in real time, over an authenticated channel and with a verifiable audit trail.
 
-They have a dynamic bill-of-material, a clear audit trail and hard inline-controls.
+Agents that implement ACS-Core run every step through a Guardian over an authenticated channel and honor its decisions in real time. With the Trace, Inspect, and Crypto profiles they also emit OpenTelemetry spans and OCSF events, expose a dynamic Agent Bill of Materials (models, MCP servers, A2A peers, tools, knowledge sources, memory stores), and gain cryptographic non-repudiation of the audit chain. ACS-Core authenticates the channel and binds the agent to the Guardian's decisions; it does not by itself make a deployment secure or its policies strict, and tamper-evidence against a compromised Guardian is the Crypto and Audit profiles, not Core.
 
-Trustworthiness of agents builds upon the foundation of existing standards (MCP and A2A), but provides value regardless. 
-It build upon cybersecurity and observability standards including OpenTelemetry, OCSF, CycloneDX, SPDX and SWID.
+ACS extends existing standards rather than reinventing them: JSON-RPC 2.0 for the wire format, OpenTelemetry and OCSF for observability, CycloneDX / SPDX / SWID for the AgBOM, MCP and A2A intact for tool and peer communication.
 
-ACS makes agents trustworthy.
+## What v0.1.0 ships
 
-!!! info "Work in progress"
-    This page is currently under development.
-    
-    **Want to contribute?** Check out the [GitHub issue](https://github.com/Agent-Control-Standard/ACS/issues/53) and join the discussion!
+- **ACS-Core** (mandatory baseline) — capability-negotiation handshake, JSON-RPC envelope, 16 native lifecycle hooks (`sessionStart`/`End`, `agentTrigger`, `userMessage`, `agentResponse`, `turnStart`/`End`, `toolCallRequest`/`Result`, `knowledgeRetrieval`, `memoryContextRetrieval`, `memoryStore`, `preCompact`/`postCompact`, `subagentStart`/`Stop`), wrapped MCP, five dispositions (`allow`, `deny`, `modify`, `ask`, `defer`), SessionContext with rolling SHA-256 chain hash, optional Intent with immutability rule, replay protection, and `system/ping` liveness.
+- **ACS-Trace** profile — OpenTelemetry semconv mapping + OCSF event-class mapping, with decisions emitted as span events on the parent step span.
+- **ACS-Inspect** / **ACS-Inspect-Dynamic** profiles — canonical AgBOM with `agbom/snapshot` and `agbom/changed`, deterministic CycloneDX / SPDX / SWID derivations.
+- **ACS-Provenance** profile — field-level `Provenance` objects with `origin`, `source_id`, `derived_from`, and an OPTIONAL wire-format `trust` enum that obeys the monotonicity rule.
+- **ACS-Crypto** profile — crypto-agile signature registry: HMAC-SHA256 baseline, ML-DSA-65 / SLH-DSA-128s for PQC, hybrid composites for transitional deployments.
+- **ACS-Audit** profile — `request_hash` on every ContextEntry so the chain commits to request content, not just step metadata.
+
+See [Conformance Profiles](./spec/conformance.md) for what each profile requires.
 
 ## Trustworthy agents are
 

docs/concepts/README.md

@@ -0,0 +1,33 @@
+# Concepts
+
+These pages define the foundational concepts ACS uses across every pillar: agents, identity, the session lifecycle, intent, provenance, capability, and trust basis. They are the single source of truth. Each pillar's specification references down into these definitions rather than restating them.
+
+This split exists because these concepts are horizontal. Intent, for example, flows through all three pillars: Instrument fires decisions against it, Trace records it as a span attribute, and Inspect catalogs what it authorized. Defining it inside any one pillar would subordinate a concept the other two depend on.
+
+## The altitude rule
+
+A normative statement lives at the altitude of its scope.
+
+- **Cross-cutting invariants** (true across pillars) are defined here and tagged **(normative)**. They belong above the pillars because that is where they are true. *e.g. "`Intent.parsed` MUST NOT be modified by the LLM or by data crossing an untrusted channel."*
+- **Mechanism requirements** (true within one pillar's enforcement) stay in that pillar. *e.g. "the Guardian MUST verify approver identity," "a client declaring `provenance_producer: none` MUST be refused at handshake."*
+
+When you add a concept, hoist the invariant and leave the mechanics. If a requirement is restated in two pillars, or buried in one but relied on by another, it is at the wrong altitude.
+
+## Pages
+
+| Concept | Covers |
+|---|---|
+| [Agents](./agents.md) | Observed Agent, Guardian Agent, Approver |
+| [Identity](./identity.md) | Principal, agent identity, descriptor types |
+| [Session lifecycle](./session-lifecycle.md) | Session, turn, step, subagent |
+| [Intent](./intent.md) | Intent as a governance concept and its immutability invariant |
+| [Provenance](./provenance.md) | Origin, source, lineage, channels |
+| [Capability](./capability.md) | Capability and authorization scope |
+| [Skill](./skill.md) | Skill as composed, loadable behavior and a trust boundary |
+| [Trust basis](./trust.md) | The spectrum from asserted to attested |
+
+## Convention
+
+Every page carries the canonical definition, any cross-cutting invariants tagged **(normative)**, and a **Referenced by** footer pointing into the pillars that consume the concept. The graph is navigable in both directions.
+
+> **Migration note.** These pages are being established as the source of truth. The pillar specifications still carry some of these definitions inline; those will be updated to reference these pages rather than restate them. Until that pass lands, treat these pages as canonical where they disagree with a pillar's inline copy.

docs/concepts/agents.md

@@ -0,0 +1,38 @@
+# Agents
+
+ACS governs the relationship between two agents and, when human or service approval is needed, a third party.
+
+## Observed Agent
+
+The AI agent under governance. It implements the ACS wire contract, emits hooks at each decision point in its lifecycle, and enforces the dispositions it receives. The Observed Agent is the subject of every AgBOM snapshot and the origin of every Trace event.
+
+The Observed Agent emits; it does not adjudicate its own actions. That separation is the core of the model.
+
+## Guardian Agent
+
+The policy authority. It receives hooks from the Observed Agent, evaluates them against deployment policy, and returns a disposition: `allow`, `deny`, `modify`, `ask`, or `defer`. It consumes AgBOM for inventory-dependent policy and emits Trace events for the decisions it makes.
+
+> **Decision logging (normative).** A Guardian MUST log every decision with its reasoning, the evaluator's model identifier, and confidence when available.
+
+## Approver
+
+A party the Guardian consults when a request falls outside standing policy and an `ask` disposition is raised. An Approver MAY be human, agent, or service. It receives an ACS-shaped request and returns an ACS-shaped decision.
+
+> **Approver authentication (normative).** Approver authentication is REQUIRED. The Guardian MUST verify the Approver's identity against policy before honoring the returned decision.
+
+The Approver's grant MAY extend `Intent.parsed` through an `intent_extension` (see [Intent](./intent.md)). In v0.1 this is single-hop: Approvers MUST NOT themselves return `ask`.
+
+*Example.* An agent requests a wire transfer outside its standing Intent. The Guardian raises `ask`; a human Approver authenticates and returns `allow` with an `intent_extension` scoped to that single request.
+
+## Trust between agents
+
+What the Observed Agent puts on the wire is asserted by the Observed Agent. The Guardian decides whether to rely on it. How much weight a given fact carries depends on its [trust basis](./trust.md), not on the fact that it arrived.
+
+---
+
+**Referenced by**
+
+- **Instrument**, [specification](../spec/instrument/specification.md): the Observed Agent emits hooks; the Guardian returns dispositions; Approvers participate via the ASK flow (§9).
+- **Trace**, [events](../spec/trace/events.md): every event names the evaluator; Guardian decisions become spans and OCSF findings.
+- **Inspect**, [AgBOM](../spec/inspect/README.md): the AgBOM is the Observed Agent's component graph.
+- See also [Identity](./identity.md) for how each party's identity is established.

docs/concepts/capability.md

@@ -0,0 +1,29 @@
+# Capability
+
+A capability is an abstract permission to do something (`filesystem.delete`, `network.egress`, `process.execute`) independent of the specific tool that exercises it. Capabilities are the vocabulary in which authorization is expressed: [Intent](./intent.md) is a set of them, and a [tool](../spec/inspect/README.md) declares the one it needs.
+
+Expressing authorization in capabilities rather than tool names lets policy reason about *what an action does* rather than *which binary does it*. Two different tools that both egress data are subject to the same `network.egress` policy.
+
+*Example.* A `file.write` tool and a `git.commit` tool both exercise `filesystem.write`. Policy written against the capability governs both, without enumerating tools.
+
+## Capability and Intent
+
+`Intent.parsed` is a capability set: the capabilities authorized for the session. A decision-eligible step that requests a capability outside that set is the central check of intent-based control: the Guardian compares the requested capability against the authorized set and the closest match.
+
+Capabilities enter the authorized set in exactly one way after Intent is fixed: an Approver's `intent_extension` through the ASK flow. See [Intent](./intent.md).
+
+## Capability in the inventory
+
+The Inspect pillar catalogs capability from the supply side: each `tool` component declares its abstract `capability`, and an `agent_capability` component groups the tools, MCP servers, and peers that compose a higher-level ability. The AgBOM is what the agent *can* do; Intent is the subset it is *authorized* to do for the session.
+
+## Capability and identity
+
+A capability is only meaningful against the [identity](./identity.md) it is granted to. Least privilege is the intersection of what the agent may do and what the principal it acts for may do; ACS supplies the capability vocabulary that makes that intersection expressible.
+
+---
+
+**Referenced by**
+
+- **Instrument**, [specification](../spec/instrument/specification.md): the requested-capability check against `Intent.parsed`, exposed in `policy_data` on a mismatch.
+- **Inspect**, [AgBOM](../spec/inspect/README.md): `tool.capability` and the `agent_capability` component type.
+- See also [Intent](./intent.md), [Identity](./identity.md), and [Agents](./agents.md).

docs/concepts/identity.md

@@ -0,0 +1,36 @@
+# Identity
+
+Identity answers who a party is: the Observed Agent, the Guardian, the Approver, and the principal on whose behalf the agent acts. It is an upstream dependency of authorization: a [capability](./capability.md) decision is only as meaningful as the identity it is bound to.
+
+> **Workstream ownership.** The identity descriptor schema is owned by the Identity workstream. This page defines the cross-cutting concept and its boundary with the pillars; the descriptor shapes and any future identity profile live with that workstream.
+
+## Principals and descriptors
+
+A principal is the authenticated party initiating or acting within a session. ACS does not invent an identity format. Identity descriptors carry a `type` discriminator that names the scheme (for example `posix_uid`, `windows_sid`, `oauth_subject`, `cert_subject`), and the descriptor shape follows that scheme.
+
+*Example.* A POSIX deployment carries `{ "type": "posix_uid", "uid": 1000 }`; an OAuth deployment carries `{ "type": "oauth_subject", "sub": "..." }`. ACS reads the discriminator and stays agnostic to the rest.
+
+Three identities are distinct and MUST NOT be conflated:
+
+- **Observed Agent identity**: which agent is under governance.
+- **Guardian identity**: which policy authority is deciding.
+- **Policy-author identity**: who authored the policy that produced a decision.
+
+## Authentication is deployment-defined
+
+> **No mandated mechanism (normative).** ACS mandates no authentication mechanism. The mechanism in use is declared at handshake. Trust schemes (for example SPIFFE, OIDC, DID, organizational PKI, or quorum signing) are deployment-defined and stay off the core wire contract.
+
+This keeps the adoption floor low: a deployment binds ACS to whatever identity infrastructure it already runs. The future Policy Attestation profile will bind policy-author identity to verifiable signatures using the ACS-Crypto registry, without pulling the trust scheme onto the wire.
+
+## Identity and trust basis
+
+An identity descriptor is itself a fact with a [trust basis](./trust.md). An asserted identity is weaker than one bound by a verified credential or signature. Policy that gates high-impact actions should require an identity at an appropriate rung of that spectrum.
+
+---
+
+**Referenced by**
+
+- **Instrument**, [specification](../spec/instrument/specification.md): `user_identity` at session start; Approver identity verification (§9); identity declared at handshake.
+- **Trace**, [extend OCSF](../spec/trace/extend_ocsf.md): agent vs human actors distinguished in emitted events.
+- **Inspect**, [AgBOM](../spec/inspect/README.md): peer identity on `a2a_peer` components.
+- See also [Agents](./agents.md), [Capability](./capability.md), and [Trust basis](./trust.md).