diff --git a/CHANGELOG.md b/CHANGELOG.md index 7138dac..0e00657 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -33,7 +33,11 @@ Publishing the GitHub release and tagging `v0.2` is a manual step after merge. ### Notes -- `evolution_stage` is reported as `human-assessed` and is always `null`. The - capability axis is scored by a human in a teardown, not derived from a spec +- `evolution_stage` is reported as `human-assessed` and is always `null` in + `aux-audit`. The capability axis is defined in + `schemas/aux-evolution-curve.yaml` (E01 Reactive → E04 Personally + Intelligent) and scored by a human in a teardown, not derived from a spec ([#5](https://github.com/auxfirst/trustkit/issues/5)). +- Licensing follows one rule: machine-readable definitions are MIT, prose is + CC BY 4.0. That now covers pattern `example.py` files as well as schemas. - A spec with no evaluation transcripts is capped at heuristic level 2. diff --git a/LICENSING.md b/LICENSING.md index 6062a6d..d595359 100644 --- a/LICENSING.md +++ b/LICENSING.md @@ -16,8 +16,9 @@ the prose, which is most of the repository by volume. It does not describe | Artifact | License | File | |---|---|---| | **Schemas** — every `.yaml` under [`schemas/`](schemas/) | **MIT** | [`schemas/LICENSE`](schemas/LICENSE) | +| **Pattern examples** — `example.py` under [`repos/agentic-ux-patterns/`](repos/agentic-ux-patterns/) | **MIT** | `SPDX-License-Identifier` in each file | | **Executable tooling** — `packages/aux-audit`, `action.yml` | **MIT** | [`packages/aux-audit/LICENSE`](packages/aux-audit/LICENSE) | -| **Prose** — onboarding, vocabulary, pattern write-ups, architecture, this file | **CC BY 4.0** | [`LICENSE`](LICENSE) | +| **Prose** — onboarding, vocabulary, pattern write-ups and diagrams, architecture, this file | **CC BY 4.0** | [`LICENSE`](LICENSE) | | **Teardown content** under `repos/agent-ux-teardowns/teardowns/` (when added) | **CC BY-NC 4.0** | declared in that tree | ## Why the schemas are MIT @@ -35,6 +36,7 @@ one click. It is just not a condition of use. ## What this means in practice - **Vendoring `aux-heuristics.yaml` into a closed-source product** — fine, MIT. +- **Copying a pattern's `example.py` into your agent** — fine, MIT. That is what it is for. - **Shipping a tool that bundles the schemas** — fine, MIT, which is why the copies under `packages/aux-audit/schemas/` need no separate carve-out. - **Quoting the onboarding docs in a blog post** — CC BY 4.0, so credit diff --git a/README.md b/README.md index c27b00c..025084b 100644 --- a/README.md +++ b/README.md @@ -77,6 +77,7 @@ Or read **[onboarding/README.md](onboarding/README.md)** — the router with all │ ├── aux-heuristics.yaml ← the 10 heuristics │ ├── trust-architecture.yaml ← the 4 trust stages │ ├── trust-gap-taxonomy.yaml ← named failure modes +│ ├── aux-evolution-curve.yaml ← the 4 capability stages (teardowns only) │ ├── trust-contract.yaml ← example Trust Contract │ ├── agent-spec.schema.yaml ← audit input format │ └── memory-policy.schema.yaml ← memory governance format @@ -157,8 +158,8 @@ GitHub renders it behind the *Cite this repository* button as APA or BibTeX. One rule: **machine-readable definitions are MIT, prose is CC BY 4.0.** -- Schemas (`schemas/*.yaml`) and tooling (`packages/aux-audit`, `action.yml`): **MIT**. Embed them; no attribution condition. -- Prose (onboarding, vocabulary, pattern write-ups): **CC BY 4.0**. +- Schemas (`schemas/*.yaml`), pattern examples (`example.py`), and tooling (`packages/aux-audit`, `action.yml`): **MIT**. Embed them; no attribution condition. +- Prose (onboarding, vocabulary, pattern write-ups and diagrams): **CC BY 4.0**. - Teardown content: **CC BY-NC 4.0** (attribution, non-commercial). GitHub's badge reads CC BY 4.0 because it detects the root **[LICENSE](LICENSE)**, which covers the prose. The schemas are not CC — see **[LICENSING.md](LICENSING.md)** and **[schemas/LICENSE](schemas/LICENSE)**. diff --git a/docs/schemas.md b/docs/schemas.md index 193346d..f63d2cc 100644 --- a/docs/schemas.md +++ b/docs/schemas.md @@ -12,6 +12,8 @@ the CLI does not duplicate heuristic text, IDs, or the trust-stage mapping. | [`schemas/agent-spec.schema.yaml`](../schemas/agent-spec.schema.yaml) | Audit input | | [`schemas/memory-policy.schema.yaml`](../schemas/memory-policy.schema.yaml) | Memory governance | +`aux-evolution-curve.yaml` is the one schema `aux-audit` never reads: capability is assessed by a human in a teardown, not derived from a spec. + License: **MIT** ([`schemas/LICENSE`](../schemas/LICENSE)) — embed or vendor them freely. See [`LICENSING.md`](../LICENSING.md) for the full map. The Evolution Curve is mentioned in diff --git a/onboarding/appendix-a-vocabulary.md b/onboarding/appendix-a-vocabulary.md index c7abe00..3aa85e6 100644 --- a/onboarding/appendix-a-vocabulary.md +++ b/onboarding/appendix-a-vocabulary.md @@ -33,5 +33,5 @@ Two tables. One for GitHub words (useful to R1 and R4 if they venture there). On | **Memory policy** | Declared scopes, retention, and user controls for persistent memory. | [schemas/memory-policy.schema.yaml](../schemas/memory-policy.schema.yaml) | | **Pattern** | A named, reusable design move that closes a specific gap. | [repos/agentic-ux-patterns](../repos/agentic-ux-patterns/README.md) | | **Teardown** | A structured review of a shipped product: `analysis.md` + `score.json`. | [repos/agent-ux-teardowns](../repos/agent-ux-teardowns/README.md) | -| **Evolution curve** | The capability axis. Assessed by a human in a teardown, never computed from a spec — a spec says what a product claims, capability is what it does. Stage names are still open. | [trustkit#5](https://github.com/auxfirst/trustkit/issues/5); home is [repos/agent-ux-teardowns](../repos/agent-ux-teardowns) | +| **Evolution curve** | The capability axis: E01 Reactive → E02 Task-Aware → E03 Context-Aware → E04 Personally Intelligent. Assessed by a human in a teardown, never computed from a spec. Unlike trust, it does not cascade. | [schemas/aux-evolution-curve.yaml](../schemas/aux-evolution-curve.yaml); applied in [repos/agent-ux-teardowns](../repos/agent-ux-teardowns) | | **Definition / Executable / Reference** | The three kinds of repo. Every repo is exactly one. | [REPO_STRUCTURE.md](../REPO_STRUCTURE.md) | diff --git a/repos/agent-ux-teardowns/README.md b/repos/agent-ux-teardowns/README.md index 4ec6470..8713972 100644 --- a/repos/agent-ux-teardowns/README.md +++ b/repos/agent-ux-teardowns/README.md @@ -31,7 +31,7 @@ Every `analysis.md`: 3. **Where the contract breaks** — named failures from [`trust-gap-classifier`](../trust-gap-classifier). 4. **Heuristic scorecard** — 10 heuristics, scored 0–3, with evidence. 5. **Trust stage** — placed on the Trust Architecture ladder. -6. **Evolution stage** — placed on the capability axis. This is the *only* place the capability axis is assessed: `aux-audit` reads a spec, and a spec states what a product claims rather than what it does. Stage names are still open — see [trustkit#5](https://github.com/auxfirst/trustkit/issues/5) — so `evolution_stage` stays `null` in teardowns until they land. +6. **Evolution stage** — placed on the capability axis, per [`aux-evolution-curve.yaml`](../../schemas/aux-evolution-curve.yaml). This is the *only* place that axis is assessed: `aux-audit` reads a spec, and a spec states what a product claims rather than what it does. A stage counts only when two distinct scenarios demonstrate it — one clever transcript is an anecdote. Capability is often uneven across surfaces, so record the spread in `evolution_surfaces` rather than averaging it away. 7. **The fix** — one concrete pattern that would move it up a stage. Every `score.json`: @@ -41,7 +41,8 @@ Every `score.json`: "product": "ChatGPT", "version": "4o, 2026-04", "trust_stage": "contextual", - "evolution_stage": null, + "evolution_stage": "aux.E03", + "evolution_surfaces": { "web": "aux.E03", "api": "aux.E01" }, "heuristics": { "aux.H01": 2, "aux.H02": 1, "aux.H03": 3, "aux.H04": 2, "aux.H05": 1, "aux.H06": 2, diff --git a/repos/agentic-ux-patterns/README.md b/repos/agentic-ux-patterns/README.md index 7f4abbd..5c0df8f 100644 --- a/repos/agentic-ux-patterns/README.md +++ b/repos/agentic-ux-patterns/README.md @@ -44,4 +44,13 @@ See [`CONTRIBUTING.md`](../../CONTRIBUTING.md). A pattern PR is rejected if any ## License -CC BY 4.0. +Same rule as the rest of TrustKit: **if you embed it, MIT; if you read it, CC BY 4.0.** + +| File | License | +|---|---| +| `example.py` — the thing you copy into your codebase | **MIT** (`SPDX-License-Identifier: MIT` in each file) | +| `README.md`, `anti-pattern.md`, `diagram.svg` | **CC BY 4.0** | + +The examples are labelled copy-paste, so a license that sends an adopter to +their legal team defeats the point. Attribution is still wanted — see +[`CITATION.cff`](../../CITATION.cff) — it is just not a condition of use. diff --git a/repos/agentic-ux-patterns/check-coverage.py b/repos/agentic-ux-patterns/check-coverage.py index 3300d2a..73dd773 100644 --- a/repos/agentic-ux-patterns/check-coverage.py +++ b/repos/agentic-ux-patterns/check-coverage.py @@ -1,4 +1,5 @@ #!/usr/bin/env python3 +# SPDX-License-Identifier: MIT """Enforce the two claims this repo makes about itself. 1. Every named gap in trust-gap-taxonomy.yaml has a pattern that closes it. diff --git a/repos/agentic-ux-patterns/patterns/behavioral-contract/example.py b/repos/agentic-ux-patterns/patterns/behavioral-contract/example.py index c8e3da7..d37f1f9 100644 --- a/repos/agentic-ux-patterns/patterns/behavioral-contract/example.py +++ b/repos/agentic-ux-patterns/patterns/behavioral-contract/example.py @@ -1,3 +1,4 @@ +# SPDX-License-Identifier: MIT """Behavioral Contract — minimal runnable example. Golden cases assert on promised properties, never on prose. Changing the pin diff --git a/repos/agentic-ux-patterns/patterns/confidence-cues/example.py b/repos/agentic-ux-patterns/patterns/confidence-cues/example.py index 2e8b061..1ad985c 100644 --- a/repos/agentic-ux-patterns/patterns/confidence-cues/example.py +++ b/repos/agentic-ux-patterns/patterns/confidence-cues/example.py @@ -1,3 +1,4 @@ +# SPDX-License-Identifier: MIT """Confidence Cues — minimal runnable example. The band is computed from evidence, never from phrasing, and the renderer has diff --git a/repos/agentic-ux-patterns/patterns/escalation-handoff/example.py b/repos/agentic-ux-patterns/patterns/escalation-handoff/example.py index 0f4fcd0..3093672 100644 --- a/repos/agentic-ux-patterns/patterns/escalation-handoff/example.py +++ b/repos/agentic-ux-patterns/patterns/escalation-handoff/example.py @@ -1,3 +1,4 @@ +# SPDX-License-Identifier: MIT """Escalation Handoff — minimal runnable example. A blocked situation produces a route with a context packet and the agent's diff --git a/repos/agentic-ux-patterns/patterns/intent-handshake/example.py b/repos/agentic-ux-patterns/patterns/intent-handshake/example.py index 59b0272..bab9476 100644 --- a/repos/agentic-ux-patterns/patterns/intent-handshake/example.py +++ b/repos/agentic-ux-patterns/patterns/intent-handshake/example.py @@ -1,3 +1,4 @@ +# SPDX-License-Identifier: MIT """Intent Handshake — minimal runnable example. Run with: python example.py diff --git a/repos/agentic-ux-patterns/patterns/memory-in-motion/example.py b/repos/agentic-ux-patterns/patterns/memory-in-motion/example.py index 6b10082..fc77766 100644 --- a/repos/agentic-ux-patterns/patterns/memory-in-motion/example.py +++ b/repos/agentic-ux-patterns/patterns/memory-in-motion/example.py @@ -1,3 +1,4 @@ +# SPDX-License-Identifier: MIT """Memory in Motion — minimal runnable example. Run with: python example.py diff --git a/repos/agentic-ux-patterns/patterns/memory-policy-scoping/example.py b/repos/agentic-ux-patterns/patterns/memory-policy-scoping/example.py index 3bc7283..9ba89f9 100644 --- a/repos/agentic-ux-patterns/patterns/memory-policy-scoping/example.py +++ b/repos/agentic-ux-patterns/patterns/memory-policy-scoping/example.py @@ -1,3 +1,4 @@ +# SPDX-License-Identifier: MIT """Memory Policy Scoping — minimal runnable example. Ancestors are readable, siblings never are, and out-of-scope hits are withheld diff --git a/repos/agentic-ux-patterns/patterns/user-aligned-objective/example.py b/repos/agentic-ux-patterns/patterns/user-aligned-objective/example.py index 9671024..e74f24c 100644 --- a/repos/agentic-ux-patterns/patterns/user-aligned-objective/example.py +++ b/repos/agentic-ux-patterns/patterns/user-aligned-objective/example.py @@ -1,3 +1,4 @@ +# SPDX-License-Identifier: MIT """User-Aligned Objective — minimal runnable example. User value and platform value are scored separately and never summed. The user's diff --git a/repos/aux-frameworks/README.md b/repos/aux-frameworks/README.md index 493df46..b191e27 100644 --- a/repos/aux-frameworks/README.md +++ b/repos/aux-frameworks/README.md @@ -14,6 +14,8 @@ /trust-architecture # 4-stage trust maturity ladder schema.yaml stages.yaml + /aux-evolution-curve # 4-stage capability axis (human-assessed) + schema.yaml /aux-audit # audit rules derived from the above schema.yaml rules.yaml diff --git a/schemas/aux-evolution-curve.yaml b/schemas/aux-evolution-curve.yaml new file mode 100644 index 0000000..633bce7 --- /dev/null +++ b/schemas/aux-evolution-curve.yaml @@ -0,0 +1,88 @@ +# Evolution Curve — capability maturity axis +# Version: 0.1.0 +# License: MIT (see schemas/LICENSE) +# +# The second axis, independent of trust. Assessed by a human in a teardown, +# never computed from an agent spec: a spec states what a product claims, +# capability is a claim about what it does. See trustkit#5. +# +# Referenced by: agent-ux-teardowns +# NOT referenced by aux-audit — the CLI reports evolution_stage: null by design. + +version: "0.1.0" +name: "Evolution Curve" +source: "auxfirst" +axis: capability + +principle: > + Capability is what the agent can attempt. Trust is whether it should be + allowed to. The two move independently, and the dangerous corner of the + grid is high capability with low trust — not low capability. + +# Unlike the Trust Architecture, this is not a ladder. +# Trust cascades: one advocacy violation collapses trust back to functional. +# Capability does not. A product that fails at E04 has not become E01; it has +# demonstrated E04 unreliably. Nothing is lost, so nothing snaps back. +cascades: false + +stages: + - id: aux.E01 + order: 1 + name: "Reactive" + question: "Does it answer what it is asked, one turn at a time?" + observed_when: + - "responds to the request in front of it" + - "no tool use, or a single tool" + - "each turn is independent of the last" + not_evidence: + - "a long answer — length is not capability" + + - id: aux.E02 + order: 2 + name: "Task-Aware" + question: "Can it carry a multi-step task to completion?" + observed_when: + - "holds a goal across several turns without being re-prompted" + - "composes two or more tools toward one outcome" + - "recovers from a failed step instead of stopping" + not_evidence: + - "a numbered plan it does not then follow" + + - id: aux.E03 + order: 3 + name: "Context-Aware" + question: "Does it use the situation, not just the request?" + observed_when: + - "reads state the user did not hand it" + - "acts differently in the same request under different circumstances" + - "operates across more than one surface with continuity" + not_evidence: + - "reciting stored preferences back — that is E02 with memory" + + - id: aux.E04 + order: 4 + name: "Personally Intelligent" + question: "Does it adapt to this particular user over time?" + observed_when: + - "behaviour differs between two users beyond their stored preferences" + - "the difference grows with use rather than being configured" + not_evidence: + - "a settings page" + - "a preference the user typed once and the agent replays" + +assessment: + by: human + in: "repos/agent-ux-teardowns" + # A product sits at one stage: the highest it reaches *reliably*. + scoring: ordinal + reliability_threshold: 2 + reliability_rule: > + A stage counts only when the teardown demonstrates it in at least two + distinct scenarios. One clever transcript is an anecdote; the curve + describes what a user can rely on. + # Capability is frequently uneven across surfaces. Record it rather than + # averaging it away — the spread is often the finding. + per_surface: optional + evidence_required: > + Every stage claim cites a reproducible scenario, per CONTRIBUTING. No + stage is assigned from a product's marketing or its own documentation.