From f8436228e0f1561edc8cffc8ed433e73b8cabe06 Mon Sep 17 00:00:00 2001 From: Wolfe-Jam Date: Thu, 12 Nov 2026 12:52:07 -0500 Subject: [PATCH] fix: Make the docs and data say only what is true - Drop origin and join dates no cited source states (A2A, agentgateway, Agent Router dates; AGENTS.md origin; OpenEnv is Hugging Face); verify no longer requires them; the panel shows "Origin" and only the facts that exist - Headline: documented lines are stated by a project's docs; examples and seams are labelled - CI wording: pushes to main, pull requests, weekly - AGENTS.md: what project.faf holds; page sentences with counts and dates; rule 7 on sourcing origin and dates - CONTRIBUTING: link ends have no direction, seam and label documented, the count and date sentences to update, Bun 1.3 rewrites bun.lock, the "Create pull request" step - Link template and skill: two ends in any order; ids only need to be unique - Titles and caption match their quotes (goose extensions, OpenSandbox skills) - Recipe: search the cache with git grep/show; handle a moved file and a renamed repository - verify: a failed fetch fails instead of passing on an old cached copy From goose's review of the whole repository at 709d522. Co-authored-by: goose Co-Authored-By: Claude Opus 5.5 --- .agents/skills/add-aaif-link/SKILL.md | 6 +++++- .github/ISSUE_TEMPLATE/propose-a-link.yml | 9 +++++---- .github/pull_request_template.md | 1 + AGENTS.md | 7 ++++--- CONTRIBUTING.md | 15 +++++++++++++-- README.md | 6 +++--- confirmed/README.md | 2 +- data/flows.json | 2 +- data/links.json | 4 ++-- data/projects.json | 6 +----- index.html | 2 +- project.faf | 4 ++-- recipes/recheck.yaml | 8 +++++++- scripts/verify.ts | 7 +++++-- 14 files changed, 51 insertions(+), 28 deletions(-) diff --git a/.agents/skills/add-aaif-link/SKILL.md b/.agents/skills/add-aaif-link/SKILL.md index f9bdb1a..6c99e67 100644 --- a/.agents/skills/add-aaif-link/SKILL.md +++ b/.agents/skills/add-aaif-link/SKILL.md @@ -15,7 +15,7 @@ A link on the map is a claim that one project's documentation states a relations ```json { - "id": "e--", + "id": "e--", "from": "", "to": "", "kind": "documented", @@ -28,6 +28,10 @@ A link on the map is a claim that one project's documentation states a relations Use `"kind": "example"` when the source only names the other project as an example. Project ids are in `data/projects.json`. + `from` and `to` are the line's two ends, in any order (the page draws no arrow). The id is `e-` plus two short names for the ends; it only has to be unique. `source` may add a `label`, shown next to the file name. + + Adding a link can change counts and dates stated on the page and in the README. CONTRIBUTING lists those sentences; update any your link makes wrong. + 4. **Check the drawing.** Open the page (`bunx serve .`) and confirm the new line does not pass through another project's box. If it does, add `"bend"` (a vertical offset in map units, positive bends down) or ask before moving a node. 5. **Add it to a flow** only if it extends a flow's story. Each step in `data/flows.json` names a link id and gives a one-sentence caption. 6. **Verify.** Run `bun scripts/verify.ts`. Every test must pass. Report the full output. diff --git a/.github/ISSUE_TEMPLATE/propose-a-link.yml b/.github/ISSUE_TEMPLATE/propose-a-link.yml index bc94eb0..a66c2a7 100644 --- a/.github/ISSUE_TEMPLATE/propose-a-link.yml +++ b/.github/ISSUE_TEMPLATE/propose-a-link.yml @@ -1,19 +1,20 @@ name: Propose a link description: A project's own documentation states a relationship to another AAIF project. -title: "Link: → " +title: "Link: ↔ " labels: ["link"] body: - type: input id: from attributes: - label: From (the project whose docs state the link) + label: One project + description: The two ends of the line, in any order. The page draws no arrow. placeholder: goose validations: required: true - type: input id: to attributes: - label: To + label: The other project placeholder: MCP validations: required: true @@ -28,7 +29,7 @@ body: id: source attributes: label: Source file URL - description: A file in the project's own repository, on its default branch. + description: The file the quote comes from, in that project's own repository, on its default branch. placeholder: https://github.com/owner/repo/blob/main/docs/page.md validations: required: true diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 1f6c120..1103fd1 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -14,4 +14,5 @@ ``` - [ ] `bun scripts/verify.ts` passes +- [ ] `bun.lock` is unchanged, unless you changed a dependency (Bun 1.3 rewrites it: `git checkout bun.lock`) - [ ] `bunx tsc --noEmit` passes diff --git a/AGENTS.md b/AGENTS.md index 5a0bb60..3b9b351 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -22,9 +22,9 @@ bunx tsc --noEmit # typecheck the verify script - `data/projects.json`: the ten projects (stage, docs, repository, technical committee name) plus the two outside nodes, "Your app" and "Models". - `data/links.json`: every line on the map. `kind` is `documented`, `example` or `seam`. - `data/flows.json`: the guided flows. Each step names a link id. -- `index.html`: the page. It reads the three data files and holds no data of its own. +- `index.html`: the page. It reads the three data files. A few sentences on it state counts and dates; CONTRIBUTING lists them. - `scripts/verify.ts`: checks every claim against the source repositories. -- `project.faf`: the repository's facts (stack, commands, data files) as structured YAML, for agents that read it. +- `project.faf`: the repository's facts (what it is, who it's for, stack, hosting, how it works) as structured YAML, for agents that read it. ## Rules @@ -33,7 +33,8 @@ bunx tsc --noEmit # typecheck the verify script 3. Stages come only from the project table in `aaif/technical-committee`. Do not infer a stage from a blog post or announcement. 4. The project list comes only from aaif.io/projects. Do not add a project that page does not list. 5. Mark new links with `"added": "YYYY-MM-DD"`, the date you verified them. -6. Do not change `index.html` to change data. Change the data files. +6. Do not change `index.html` to change data. Change the data files. If a change makes a count or date on the page or in the README wrong, update that sentence too (CONTRIBUTING lists them). +7. A project's `origin` and `joined` appear only when a cited source states them (the AAIF or Linux Foundation announcement, aaif.io). Otherwise leave them out. ## Leave alone diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e210424..b99eb00 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -14,13 +14,22 @@ To add a path yourself, add a flow to `data/flows.json`. Each step names a link - **A quote** from the source project's docs, copied as a reader sees it. - **A source file** in that project's own repository, on its default branch. Docs pages and READMEs are preferred over blog posts, issues and release notes. -- **A kind:** `documented` when the docs state the link, `example` when they only name the other project as an example. +- **A kind:** `documented` when the docs state the link, `example` when they only name the other project as an example. (`seam` marks an overlap no document settles; its quote is the map's own wording and it needs no source.) +- **Two ends:** `from` and `to` are the two projects the line connects. The page draws no arrow, so their order doesn't matter. The source is whichever project's docs the quote comes from. +- **Optionally a `label`** in `source`, shown next to the file name (for example `README, Key Features`). The [add-aaif-link skill](.agents/skills/add-aaif-link/SKILL.md) walks through the steps. ## Confirm your project -If you work on one of the projects, open its "Check your details" issue. Its confirm link opens `confirmed/.md` with the project's details as the map shows them; if they're right, add your GitHub handle after `Verified by: @` and press "Propose new file". If something's wrong, say so in the issue or fix it in a pull request. [confirmed/README.md](confirmed/README.md) has more. +If you work on one of the projects, open its "Check your details" issue. Its confirm link opens `confirmed/.md` with the project's details as the map shows them; if they're right, add your GitHub handle after `Verified by: @`, press "Propose new file", then "Create pull request". If something's wrong, say so in the issue or fix it in a pull request. [confirmed/README.md](confirmed/README.md) has more. + +## Sentences that state counts and dates + +A few sentences hold numbers the data can change. When your change makes one wrong, update it in the same pull request: + +- README, "What it shows": the counts of projects, links, examples, seams and flows. +- `index.html`: the line under the title (project count and month), "MCP is the hub" and "MCP sits in the middle" (how many projects link to MCP), the stage lists and the committee table's date, and the overview's sentence about links added in a check. ## What the map does not take @@ -36,6 +45,8 @@ bun scripts/verify.ts bunx tsc --noEmit ``` +CI uses Bun 1.4.4. Bun 1.3 can't read `bun.lock` and rewrites it on `bun install`; if `bun.lock` shows as changed, run `git checkout bun.lock` before you commit. + Every test must pass. Paste the full verify output in the pull request. ## Commits diff --git a/README.md b/README.md index b0bcf0d..001f472 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # AAIF Stack Map -An interactive map of the ten [Agentic AI Foundation](https://aaif.io/projects) projects and the links between them. Every line on the map is a link that one project's own documentation states, with the quote and the file it comes from. +An interactive map of the ten [Agentic AI Foundation](https://aaif.io/projects) projects and the links between them. Every documented line on the map is a link one project's own documentation states, with the quote and the file it comes from; examples and open seams are labelled as such. A community map by James Wolfe, AAIF Ambassador, built from each project's own documentation. @@ -36,7 +36,7 @@ The script clones each source repository (shallow, into `.cache/repos`) and runs | 2 · Stages | Every stage matches the technical committee table, and the map has exactly the projects the table lists. | | 3 · Data | The data files are consistent: unique ids, links between real nodes, flow steps that name real links, complete project records. | -It prints every test and exits non-zero if any fails. CI runs it on every push and pull request and once a week; when the weekly run finds drift, it opens an issue labelled `drift`. +It prints every test and exits non-zero if any fails. CI runs it on pushes to `main`, on pull requests and once a week; when the weekly run finds drift, it opens an issue labelled `drift`. ## Contribute @@ -61,7 +61,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md). | File | Holds | | --- | --- | -| `data/projects.json` | Projects: stage, docs, repository, contributor, date joined, and map position | +| `data/projects.json` | Projects: stage, docs, repository, origin and date joined (only where a cited source states them), and map position | | `data/links.json` | Links: ends, kind, quote, source repository and path | | `data/flows.json` | Flows: ordered link ids with one caption each | diff --git a/confirmed/README.md b/confirmed/README.md index f427640..5be1315 100644 --- a/confirmed/README.md +++ b/confirmed/README.md @@ -2,6 +2,6 @@ One file per project: the project's details as the map showed them when someone from that project confirmed them. Git records who confirmed and when. -A file is named after the project's id in [`data/projects.json`](../data/projects.json) (`goose.md`, `mcp.md`, `agw.md`, …). Each project's "Check your details" issue has a link that opens its file already filled in, ending with `Verified by: @`. Add your GitHub handle after the `@` and press "Propose new file"; once it's merged, you're listed as a contributor. +A file is named after the project's id in [`data/projects.json`](../data/projects.json) (`goose.md`, `mcp.md`, `agw.md`, …). Each project's "Check your details" issue has a link that opens its file already filled in, ending with `Verified by: @`. Add your GitHub handle after the `@`, press "Propose new file", then "Create pull request"; once it's merged, you're listed as a contributor. A file is kept as it was confirmed. If the map's data changes later, the file still shows what was agreed then. The verify script checks only that each file is named after a project. diff --git a/data/flows.json b/data/flows.json index 5c67cae..7c3f954 100644 --- a/data/flows.json +++ b/data/flows.json @@ -13,7 +13,7 @@ }, { "link": "e-goose-mcp", - "caption": "Its tools arrive as extensions, and every extension is an MCP server." + "caption": "Its tools arrive as extensions, which are based on MCP." }, { "link": "e-sandbox-mcp", diff --git a/data/links.json b/data/links.json index 099a10f..96ccc96 100644 --- a/data/links.json +++ b/data/links.json @@ -30,7 +30,7 @@ "from": "goose", "to": "mcp", "kind": "documented", - "title": "goose extensions are MCP servers", + "title": "goose extensions are based on MCP", "quote": "Extensions are based on the Model Context Protocol (MCP)", "source": { "repo": "aaif-goose/goose", @@ -173,7 +173,7 @@ "from": "sandbox", "to": "skills", "kind": "documented", - "title": "OpenSandbox ships skills as SKILL.md", + "title": "OpenSandbox's CLI installs its skills, as SKILL.md for opencode", "quote": "The CLI ships with built-in OpenSandbox skills for coding agents and agent-oriented tools. … `./.agents/skills//SKILL.md`", "source": { "repo": "opensandbox-group/OpenSandbox", diff --git a/data/projects.json b/data/projects.json index 72580a5..b23de3a 100644 --- a/data/projects.json +++ b/data/projects.json @@ -25,7 +25,6 @@ "layer": "Context", "x": 600, "y": 60, - "origin": "OpenAI, with others", "joined": "Dec 2025 (launch project)", "stage": "Impact", "role": "A predictable place for the instructions and context that help coding agents work on a project.", @@ -107,7 +106,6 @@ "x": 760, "y": 250, "origin": "Google", - "joined": "Aug 17, 2026", "stage": "Growth", "role": "An open standard for communication and interoperability between AI agents. Its Agent Card lists an agent’s “skills”, a separate idea from the Agent Skills format.", "repo": "a2aproject/A2A", @@ -122,7 +120,6 @@ "x": 260, "y": 355, "origin": "Envoy AI Gateway, renamed", - "joined": "Sep 9, 2026", "stage": "Growth", "role": "The control plane for agent traffic: one OpenAI-compatible API for models and MCP servers, with a preview guide for A2A traffic.", "repo": "theagentrouter/agent-router", @@ -137,7 +134,6 @@ "x": 740, "y": 355, "origin": "Solo.io", - "joined": "Jun 4, 2026", "stage": "Growth", "role": "One high-performance gateway for service, LLM and MCP traffic, with A2A support.", "repo": "agentgateway/agentgateway", @@ -166,7 +162,7 @@ "layer": "Run & train", "x": 590, "y": 450, - "origin": "Hugging Face, with Meta-PyTorch", + "origin": "Hugging Face", "joined": "Oct 22, 2026", "stage": "Growth", "role": "Environments for training and evaluating agents with reinforcement learning, shared through a hub. Its /mcp route uses MCP’s message format over its own HTTP transport; RFC 003 (still in review) plans standard Streamable HTTP.", diff --git a/index.html b/index.html index 411fc51..4ce2d0f 100644 --- a/index.html +++ b/index.html @@ -282,7 +282,7 @@

Sources

const es = EDGES.filter(e => (e.a === id || e.b === id) && (!e.seam || seamsBox.checked)); highlight([id, ...es.map(e => e.a === id ? e.b : e.a)], es.map(e => e.id)); panel.innerHTML = `

${esc(n.layer)} · ${esc(n.kind)}

${esc(n.name)}

${stageChip(n)}

${esc(n.role)}

` + - (n.ext ? '' : `
`) + + (n.ext ? '' : `
${n.origin ? `
Origin
${esc(n.origin)}
` : ''}${n.joined ? `
Joined AAIF
${esc(n.joined)}
` : ''}
Docs
${esc(DOCS[n.id].replace(/^https:\/\/(www\.)?/, ''))}
Repository
${esc(n.repo.replace('https://github.com/', ''))}
`) + `

${es.length} ${es.length === 1 ? 'link' : 'links'} on the map

`; } function showEdge(eid) { diff --git a/project.faf b/project.faf index 57deea5..9d97006 100644 --- a/project.faf +++ b/project.faf @@ -1,7 +1,7 @@ faf_version: "3.0" project: name: aaif-stack-map - goal: An interactive map of the ten [Agentic AI Foundation](https://aaif.io/projects) projects and the links between them. Every line on the map is a link that one project's own documentation states, with the quote and the file it comes from. + goal: "An interactive map of the ten [Agentic AI Foundation](https://aaif.io/projects) projects and the links between them. Every documented line on the map is a link one project's own documentation states, with the quote and the file it comes from; examples and open seams are labelled as such." main_language: TypeScript type: html # found: index.html (vanilla, no frontend framework) stack: @@ -26,7 +26,7 @@ stack: storage: slotignored human_context: who: "Developers, newcomers and AAIF ambassadors working out how the AAIF projects fit together, and the projects' maintainers, who can confirm their details." - what: An interactive map of the ten [Agentic AI Foundation](https://aaif.io/projects) projects and the links between them. Every line on the map is a link that one project's own documentation states, with the quote and the file it comes from. + what: "An interactive map of the ten [Agentic AI Foundation](https://aaif.io/projects) projects and the links between them. Every documented line on the map is a link one project's own documentation states, with the quote and the file it comes from; examples and open seams are labelled as such." why: "One page for how the AAIF projects connect, every line backed by a project's own docs." where: "https://wolfe-jam.github.io/aaif-stack-map/ (source: github.com/Wolfe-Jam/aaif-stack-map)" when: "Built November 2026 against aaif.io/projects and the technical committee table; re-verified weekly in CI." diff --git a/recipes/recheck.yaml b/recipes/recheck.yaml index f7774bf..dd1794e 100644 --- a/recipes/recheck.yaml +++ b/recipes/recheck.yaml @@ -10,9 +10,15 @@ prompt: | 1. Run `bun install` if node_modules is missing, then run `bun scripts/verify.ts --json report.json`. 2. If every test passes, report the full test output, every line, not a summary, and stop. 3. For each failing test: - - Quote not found: search the same repository (cached under .cache/repos) for the current wording. + - Quote not found: search the same repository for the current wording. The cache under .cache/repos + holds only git data, no working files: use `git -C .cache/repos/_ grep -n "" HEAD` + and `git -C .cache/repos/_ show HEAD:`. If the project still states the link, update the quote and path in data/links.json. If it no longer does, remove the link and any flow step in data/flows.json that uses it. + - Source file not found: the file may have moved. Find the quote with `git grep` in the same repository + and update the path in data/links.json. + - Repository not reachable: it may have been renamed or moved. If GitHub redirects the old name, + update the repo in data/links.json (and data/projects.json); if it is gone, report it. - Stage mismatch: update the stage in data/projects.json to the committee table's value. - Project missing from the map, or count mismatch: do not add the project yourself. Report it. 4. Run `bun scripts/verify.ts` again and report the full output. diff --git a/scripts/verify.ts b/scripts/verify.ts index e2b81bf..711817c 100644 --- a/scripts/verify.ts +++ b/scripts/verify.ts @@ -50,8 +50,10 @@ const dirFor = (repo: string): string => join(reposDir, repo.replace("/", "_")); function ensureRepo(repo: string): boolean { const dir = dirFor(repo); if (existsSync(join(dir, ".git"))) { + // A failed fetch must not pass on an old cached copy: the quotes would not be current. const fetched = run(["git", "fetch", "-q", "--depth", "1", "origin", "HEAD"], dir); - if (fetched.ok) run(["git", "update-ref", "HEAD", "FETCH_HEAD"], dir); + if (!fetched.ok) return false; + run(["git", "update-ref", "HEAD", "FETCH_HEAD"], dir); return run(["git", "rev-parse", "HEAD"], dir).ok; } mkdirSync(reposDir, { recursive: true }); @@ -95,7 +97,8 @@ for (const [key, f] of Object.entries(flows)) { record(3, `flow ${key}: every step names a link`, missing.length === 0, missing.length ? `unknown: ${missing.join(", ")}` : `${f.steps.length} steps`); } for (const p of projects) { - const gaps = (["repo", "docs", "stage", "committeeName", "origin", "joined"] as const).filter(k => !p[k]); + // origin and joined are optional: shown only where a cited source states them (AGENTS.md rule 7). + const gaps = (["repo", "docs", "stage", "committeeName"] as const).filter(k => !p[k]); record(3, `project ${p.id}: required fields present`, gaps.length === 0, gaps.length ? `missing: ${gaps.join(", ")}` : "repo, docs, stage, committee name"); if (p.docs) record(3, `project ${p.id}: docs link is https`, p.docs.startsWith("https://"), p.docs); if (p.stage) record(3, `project ${p.id}: stage is a known stage`, (STAGES as readonly string[]).includes(p.stage), p.stage);
Contributed by
${esc(n.origin)}
Joined AAIF
${esc(n.joined)}
Docs
${esc(DOCS[n.id].replace(/^https:\/\/(www\.)?/, ''))}
Repository
${esc(n.repo.replace('https://github.com/', ''))}