Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 15 additions & 38 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,14 +2,20 @@

## Unreleased

(nothing yet)

## 0.2.1-prototype — 2026-10-16

**Docs / cookbook prototype label.** Map v2 **Core schema and required fields are unchanged** from `0.2.0-draft`. This release makes optional profiles and teaching materials legible. It is **not** a finished interoperability standard and does **not** mark Core stable.

### Added

- Cookbook: `hub-umbrella.md`, `stream-packs.md`, `local-bootstrap.md` (optional profiles / teaching patterns)
- Cookbook: `done-bar.md`, `schema-pinning.md`, `glass-box-factory.md` (pattern only), `orchestrator-session.md` (harness-agnostic manager/worker shape)
- Examples: `examples/hub-umbrella/` (synthetic multi-node shell + child map), `examples/stream-packs/` (orientation, local index example, research / release-check / accept-default samples)
- Examples: `examples/invalid/anti-multi-stream-open.md`, `anti-recursive-preload.md` (disclosure anti-patterns); `examples/shell/README.md` cross-link to hub-umbrella
- Templates: `templates/orientation.md`, `templates/stream-pack.yaml` stubs
- README: Core vs profile table; progressive disclosure footnote that profile bootstrap is not Core L0; links to new cookbook pages and templates; optional **Disclosure profile** conformance row; prototype-narrative note (unreleased)
- README: Core vs profile table; progressive disclosure footnote that profile bootstrap is not Core L0; links to new cookbook pages and templates; optional **Disclosure profile** conformance row
- SPEC: overlays, extension layout keys, optional `profiles` block, non-normative optional local files (schema-preexisting surfaces; prose only)
- MOTIVATION: experiment metrics sketch (wrong-home, index degrade honesty, accept-bar catches)
- CONTRIBUTING: stream packs / accept bars / orientation templates are **profile PRs**, not Core MUST; L0 budget reminder for profile bootstrap
Expand All @@ -18,41 +24,25 @@

- Core L0 remains map-only for Orientation conformance
- Dogfood-inspired profiles (stream packs, thin orientation, accept bar, thin runtime dispatcher, done bar) are **optional**; no specific agent harness or multi-agent runtime is required
- Status narrative: working-prototype cookbook alongside experimental Map v2 — still not a finished interop standard
- Status narrative: working-prototype **docs** alongside experimental Map v2 Core
- Glass-box factory and orchestrator session are **patterns** documented in cookbook — this repo does **not** ship conductor CLI
- `what-not-to-copy.md`: factory/orchestrator/status-macro/dispatcher/index anti-copies; copy stream-pack, done-bar, and hub-umbrella **ideas**
- Schema pinning: immutable tag/commit; MUST NOT validate against tip; dual gist vs in-repo honesty

### Not changed

- Map v2 required fields and `resourceRef` semantics
- Schema document version / git tag (`0.2.0-draft` / `v0.2.0-draft`)
- Core size goals (profiles stay out of mandatory L0)
- `schemas/map.schema.json` document shape (still the v2 contract introduced in `0.2.0-draft`)

### Unreleased candidate notes (not tagged)

Draft text for a possible future **docs-only** `0.2.1-prototype` label — **candidate only**. Do **not** treat as released; **no** git tag from this changelog alone; Core remains experimental.

```text
## 0.2.1-prototype — (date TBD; unreleased candidate)

### Added
- Cookbook: hub umbrella, stream packs, local bootstrap, done-bar, schema-pinning,
glass-box-factory (pattern), orchestrator-session (optional profiles / patterns)
- Examples: hub-umbrella, stream-packs samples; invalid disclosure anti-pattern notes
- Templates: orientation.md, stream-pack.yaml stubs
- SPEC clarifications: overlays, extension layout keys, profiles block (schema-preexisting)
### Git tag

### Clarified
- Core L0 remains map-only for Orientation conformance
- Dogfood-inspired profiles are optional; multi-agent runtimes not required
- Status: working-prototype docs; still not a finished interop standard
- Documents / CHANGELOG: `0.2.1-prototype` (no `v`)
- Git tag: `v0.2.1-prototype` (with `v`)

### Not changed
- Map v2 required fields / resourceRef semantics
```
## 0.2.0-draft — 2026-09-11

## 0.2.0-draft — Unreleased
Map v2 introduction (historical). Prefer pinning **`v0.2.1-prototype`** (or later) for docs+schema teaching set; Core map rules below still apply.

### Changed

Expand Down Expand Up @@ -88,17 +78,4 @@ Draft text for a possible future **docs-only** `0.2.1-prototype` label — **can

## 0.1.0-draft — 2026-09-08

### Added

- Initial public seed: README, SPEC, white paper outline, MIT license
- JSON Schemas: map + artifact envelope
- Templates: minimal map, capability + decision artifacts
- Examples: single-repo and multi-zone maps
- Cookbook: brownfield init, what not to copy from incubators

### Design stance

- Progressive disclosure (L0 = map only)
- Zone = placement/coordination scope (ownership not implied)
- `write` allow-list may be empty; optional `access`
- External zones: schema-compatible, provisional, not required for Core orientation
Initial public draft (v1 zones map). Superseded by Map v2; see `legacy/v1/`.
5 changes: 3 additions & 2 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,9 @@ Thank you for helping keep the Core **small**.

| Place | Form |
|-------|------|
| Documents / CHANGELOG | `0.2.0-draft` (no `v`) |
| Git tags | `v0.2.0-draft` (with `v`) |
| Documents / CHANGELOG | `0.2.1-prototype` (no `v`) |
| Git tags | `v0.2.1-prototype` (with `v`) |
| Prior Core intro label | `0.2.0-draft` / historical commits — Map v2 rules unchanged in `0.2.1-prototype` |

## What belongs in Core vs elsewhere

Expand Down
2 changes: 1 addition & 1 deletion MOTIVATION.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# AAP Motivation (outline)

**Status:** outline paired with Map v2 SPEC 0.2.0-draft
**Status:** outline paired with Map v2 SPEC `0.2.1-prototype` (Core lineage `0.2.0-draft`)

---

Expand Down
14 changes: 6 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
# Agent Artifact Protocol (AAP)

**Version:** 0.2.0-draft
**Status:** experimental Map v2 + dogfood-informed **optional** profiles (cookbook)
**Version:** 0.2.1-prototype
**Status:** experimental Map v2 Core + dogfood-informed **optional** profiles (working-prototype **docs**)
**License:** MIT
**Git tag form:** `v0.2.0-draft` (documents omit the `v` prefix)
**Git tag form:** `v0.2.1-prototype` (documents omit the `v` prefix)

> **AAP makes repository context addressable without requiring repository context to be loaded.**

> **Breaking draft revision.** `0.2.0-draft` replaces the historical v1 `zones` map with a repository-oriented v2 `workspace` / `self` / `nodes` map. The v1 material is retained under `legacy/v1/` for historical reference and is not compatible with v2.
> **Map v2** (`0.2.0-draft` lineage) replaced the historical v1 `zones` map with a repository-oriented `workspace` / `self` / `nodes` map. **`0.2.1-prototype`** is a **docs/cookbook** label on that same Core — optional profiles and examples, **not** a claim that Core is a finished interop standard. v1 material remains under `legacy/v1/`.

AAP is a **runtime-agnostic filesystem convention** for:

Expand Down Expand Up @@ -57,7 +57,7 @@ For editor/CI validation, pin this repository by immutable tag or commit (see [`

```bash
# conceptual pin (no runtime fetch during normal agent sessions)
# git clone --depth 1 --branch v0.2.0-draft \
# git clone --depth 1 --branch v0.2.1-prototype \
# https://github.com/gitpash/agent-artifact-protocol.git /tmp/aap
# mkdir -p .aap && cp /tmp/aap/templates/minimal-map.yaml .aap/map.yaml
```
Expand Down Expand Up @@ -203,9 +203,7 @@ Only after B helps, try optional profiles (one stream pack, hub umbrella, accept

## Status

`0.2.0-draft` — experimental Map v2 blueprint with a **dogfood-informed cookbook**. Useful in multi-repo pilots. **Not** production infrastructure or a finished interoperability standard. Core remains draft; optional profiles do not promote Core to stable.

**Prototype narrative (docs only):** Unreleased cookbook work prepares a possible later `0.2.1-prototype` **docs** label (see CHANGELOG candidate notes). That is **not** a claim that Core is stable, and **no** prototype git tag is cut from cookbook PRs alone.
`0.2.1-prototype` — experimental Map v2 Core **plus** a dogfood-informed **cookbook prototype** (hub umbrella, stream packs, local bootstrap, done-bar, schema pinning, session patterns). Useful in multi-repo pilots. **Not** production infrastructure or a finished interoperability standard. Optional profiles do **not** promote Core to stable; pin with git tag `v0.2.1-prototype` (or commit SHA).

Feedback is especially welcome on:

Expand Down
4 changes: 2 additions & 2 deletions SPEC.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,8 @@

**Name:** Agent Artifact Protocol (AAP)
**Kind:** filesystem convention + JSON Schema
**Version:** 0.2.0-draft
**Status:** experimental
**Version:** 0.2.1-prototype
**Status:** experimental Core (Map v2) + prototype docs/cookbook (profiles optional)

AAP makes repository context addressable without requiring it to be loaded. It is a small, runtime-agnostic navigation convention for repositories and optional durable artifacts. It is not a context engine, agent framework, retrieval protocol, dependency graph, or authorization system.

Expand Down
2 changes: 1 addition & 1 deletion cookbook/brownfield-init.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ Add AAP orientation to an existing repo **without** rewriting its docs system.
Record the immutable v2 tag or commit in a one-line note, e.g. `.aap/VERSION`. Do not validate against a floating branch tip. Details: [`schema-pinning.md`](./schema-pinning.md).

```text
v0.2.0-draft
v0.2.1-prototype
https://github.com/gitpash/agent-artifact-protocol
```

Expand Down
8 changes: 4 additions & 4 deletions cookbook/schema-pinning.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,15 +24,15 @@ Agents then “pass” maps that other clones reject — or the reverse.

| Style | Example | Notes |
|-------|---------|--------|
| **Git tag** | `v0.2.0-draft` | Preferred for humans; matches CHANGELOG language with `v` prefix on tags |
| **Git tag** | `v0.2.1-prototype` | Preferred for humans; matches CHANGELOG language with `v` prefix on tags |
| **Commit SHA** | full or abbreviated immutable SHA | Best when tags lag |
| **Vendored file** | copy `schemas/map.schema.json` into consumer | Offline CI; bump deliberately |
| **Contract sidecar** | e.g. `.aap/aap-contract.yaml` with `revision` + `sha256` | Optional; consumer convention |

Conceptual pin (no fetch during normal sessions):

```bash
# git clone --depth 1 --branch v0.2.0-draft \
# git clone --depth 1 --branch v0.2.1-prototype \
# https://github.com/gitpash/agent-artifact-protocol.git /tmp/aap
# cp /tmp/aap/schemas/map.schema.json path/to/consumer-tools/
```
Expand All @@ -41,7 +41,7 @@ One-line consumer note (example):

```text
# .aap/VERSION (or equivalent local note)
v0.2.0-draft
v0.2.1-prototype
https://github.com/gitpash/agent-artifact-protocol
```

Expand All @@ -51,7 +51,7 @@ https://github.com/gitpash/agent-artifact-protocol
# Consumer-local — not required by Map v2 Core
schema:
name: map.schema.json
pin: v0.2.0-draft # or commit SHA
pin: v0.2.1-prototype # or commit SHA
# sha256: <hex of pinned bytes>
source: https://github.com/gitpash/agent-artifact-protocol
```
Expand Down
Loading