docs: AEP tutorial; upstream report and following-upstream skill; verify aep 0.64.0 / ess 0.39.0; release 0.18.0

.agents/skills/following-upstream/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: following-upstream
+description: Bring this repository up to date with everything it takes from other repositories — the aep, ess, worktree, metaharness and connectors releases its plugins drive, the workflows pinned by commit, and the issues its skills work around. Use when asked to check for upstream releases, sync or refresh agentplugins, follow a new release of aep or ess, or when the Tools check fails with "is newer than verified.json". Run it on a schedule.
+---
+
+# Following upstream
+
+This repository teaches agents to use CLIs it does not build. Every release of one of them can
+rename a command, change a format, fix a bug a skill works around, or add something worth teaching.
+This skill is the loop that finds those changes and carries them here: detect, read, update,
+verify, release, then follow the change downstream.
+
+## 1. Detect
+
+```console
+cargo run --locked --bin agentplugins-check -- upstream > ~/.cache/agentplugins-upstream.md
+```
+
+The report has three sections, and ends with `<n> item(s) moved.` A run with 0 moved items ends
+this skill: report that and stop.
+
+| section | moved means | where the pin lives |
+|---|---|---|
+| Releases | a newer release than the pin, with its `CHANGELOG.md` sections since the pin | `verified.json` (aep, ess, worktree), `.github/workflows/eval.yml` (metaharness), the `integrating` skill (connectors) |
+| Workflow pins | `main` of a `beyond10x/*` repository is past the commit a workflow uses | `.github/workflows/*.yml` |
+| Cited issues | an issue a skill or page cites is closed | the file that cites it |
+
+## 2. Read, and sort every change
+
+Read each changelog section in full. Sort each entry into one row; an entry may land in two.
+
+| kind | what to do here |
+|---|---|
+| a command, flag or verb removed or renamed | fix every spelling in `plugins/` and `website/docs/`; `tools` names each one it no longer finds |
+| a format, store or protocol version | the skills' version tables and upgrade paths (`aep:upgrade`, `ess:specifying` `later-formats.md`, the store section of `aep:planning`) |
+| a new capability an agent would use | the skill that owns the activity (`ess:hardening`, `ess:testing-conformance`, `aep:implementing` …), one paragraph, with the command |
+| a fix for something a skill works around | remove the workaround when the release carries the fix; cite the release |
+| internal only (tests, refactors, CI) | nothing |
+
+For a **closed cited issue**, read the closing change and remove or rewrite the text that cites it.
+For a **moved workflow pin**: a file that starts `Generated by atlas docs reconcile` is not edited
+here; it moves when Atlas reconciles. Report it. A hand-written workflow moves by one commit that
+names the new pin and what changed.
+
+For **connectors**, the `integrating` skill deliberately targets the v1 line (`v0.7.2`) while the
+newest releases are the v2 lineage. A moved connectors release is a decision for the operator, not
+an edit: report it with its changelog, once.
+
+## 3. Update
+
+In a managed worktree from `origin/main`. The rules of `AGENTS.md` hold: no CLI version in plugin
+text (R5), grouped verbs, no retired names. Edit what § 2 sorted; do not move `verified.json` yet.
+A store `protocols:` pin in `.engineering/project.yaml` moves to the new aep release commit.
+
+## 4. Verify
+
+1. `cargo run --locked --bin agentplugins-check -- tools` — every spelled command against the newest
+   releases, the ESS syntax example, and the ESS tutorial's specification, suite and `go test`.
+2. A trial round per [`improving-by-trial`](../improving-by-trial/SKILL.md): the ESS trials and
+   `ess-tutorial` for a new release of ess, `aep-backlog` and `aep-tutorial` for a new release of aep. A run
+   worse than `trials/baseline.json` is triaged there; a defect in the other repository becomes a
+   `trial-finding` issue there, and a workaround here that cites it.
+3. Then, and only then, `verified.json` moves to the new releases.
+4. `task check` and `task site-build`.
+
+## 5. Release
+
+The release in `AGENTS.md` § Publishing: `CHANGELOG.md` names the releases verified against and what
+changed for an agent; versions agree; bot commits, a pull request, merge on the required checks, a
+bare annotated tag, then verify the release run, the GitHub Release, its assets and `SHA256SUMS`.
+
+## 6. Downstream
+
+- **The website's Start page** pins agentplugins, aep and ess releases
+  (`beyond10x/website` `data/experiences.json`, its validator and contract test). Move them in one
+  website pull request: lock only the `agentplugins` source beside `main`'s lock, commit it, render
+  `atlas docs snapshot` from a managed Atlas checkout at `origin/main`, and pass `npm run gate`.
+- **Publication.** After the merge, the next Atlas "Publish unified documentation" run must pass.
+  One broken link anywhere fails every source's publication; read the failed run's log before
+  assuming the delay is Atlas's.
+- Tell whoever asked for the release (a peer session, an issue) which version carries it.
+
+## Report
+
+Per moved item: what moved, what changed here (commit), or why nothing did. Then the trial numbers
+against the baseline, the release and its verification, the issues filed, and anything left for the
+operator (a connectors lineage decision, an Atlas-generated pin).

.claude/skills/following-upstream

@@ -0,0 +1 @@
+../../.agents/skills/following-upstream

.engineering/evidence/story/shared-docs-toolchain/20260928T095338Z-6e4f2e2a0e6b.json

@@ -0,0 +1,13 @@
+{
+  "at": "2026-09-28T09:53:38Z",
+  "actor": "human:timo",
+  "artifact": "story:shared-docs-toolchain",
+  "kind": "story",
+  "revision": 3,
+  "change": {
+    "change": "evidence",
+    "kind": "test_result",
+    "source": "b10x-docs-bundle on 44bb0ee with docs-system 339b4b8 (contains 1d4c026)",
+    "reference": "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/beyond10x/agentplugins/actions/runs/36406238132"
+  }
+}

.engineering/planning/dependency-blocker/governed-dogfood-run.md

@@ -0,0 +1,15 @@
+---
+format: aep.planning-md/3
+id: dependency-blocker:governed-dogfood-run
+kind: dependency-blocker
+status: open
+title: aep story:governed-dogfood-run has not landed; the driven walk does not reach complete
+relations:
+- blocks: story:drive-entry-skill
+revision: 1
+---
+# Blocker: the aep governed dogfood run
+
+`story:drive-entry-skill` says in its Out of Scope that it is blocked until the `aep` repository's
+`story:governed-dogfood-run` lands. That story is `draft` on `beyond10x/aep` `origin/main`
+(b11db555f4, read 2026-09-28). Cleared when it reaches `implemented` there.

.engineering/planning/dependency-blocker/metaharness-links-aep-0-55.md

@@ -0,0 +1,20 @@
+---
+format: aep.planning-md/3
+id: dependency-blocker:metaharness-links-aep-0-55
+kind: dependency-blocker
+status: open
+title: metaharness links aep 0.55.0, so no eval case can be recorded beside aep 0.64.0
+relations:
+- blocks: story:plugin-eval-cases
+revision: 2
+---
+# Blocker: metaharness links aep 0.55.0
+
+aep 0.64.0 moved live evaluation to `metaharness aep drive eval run`. metaharness 0.8.0 and its
+`main` (13a8378) link aep at 28abe09 (0.55.0) and refuse every case with EVAL-RUN-017 when the `aep`
+on the child's PATH is 0.64.0 (observed 2026-09-28 on the four plan-critic cases). Filed as
+beyond10x/metaharness#10. Cleared when a metaharness release links aep 0.64.0 or newer.
+
+Ready for then: `fixtures/library-reservations-drafted` (the AEP tutorial's store before its
+critics ran) is the working tree for the four plan-critic cases, whose tasks now name
+`epic:book-reservations`.

.engineering/planning/story/aep-tutorial.md

@@ -0,0 +1,41 @@
+---
+format: aep.planning-md/3
+id: story:aep-tutorial
+kind: story
+status: active
+title: A public tutorial takes the ESS tutorial's library to a governed, critiqued plan and one implemented story with AEP
+summary: 'tutorials/first-governed-plan: adopt, a new noun modelled in ESS first, decompose, scope, critic panel, one wave; real output; held true by tools and a trial.'
+relations:
+- informed_by: story:ess-tutorial-and-onboarding
+scope:
+- confidence: cited
+  path: trials/aep-tutorial
+- confidence: cited
+  path: website/docs/tutorials
+revision: 5
+transitions:
+- {from: "draft", to: "proposed", at: "2026-09-28T13:12:54Z", actor: "human:timo", revision: 2}
+- {from: "proposed", to: "active", at: "2026-09-28T13:12:54Z", actor: "human:timo", revision: 3}
+---
+# Story: a public AEP tutorial
+
+## Outcome
+A developer who finished *Your first ESS specification* continues on the same library repository:
+adopts an AEP planning store, asks for a feature that introduces a new noun, and gets a modelled
+noun, a decomposed and scoped plan argued with by the critic panel, and one story implemented in a
+wave with its evidence recorded. Every output on the page is from a real run.
+
+## Context
+- `website/docs/golden-path.md` records AEP 0.44.0 and ESS 0.5.1 output on an `aep.project/1`
+  store; new stores are `aep.project/5` since aep 0.62.
+- The ESS tutorial (0.17.0) ends with "a tutorial like this one for AEP follows".
+
+## Acceptance
+- `website/docs/tutorials/first-governed-plan.md` exists, recorded with the newest aep and ess.
+- `agentplugins-check tools` checks every command the page spells against the newest releases.
+- A trial gives a fresh agent only the page and reaches a valid store with the planned stories and
+  one story implemented.
+- `task check` and `task site-build` pass.
+
+## Out of Scope
+Driving a story with `metaharness aep drive` (blocked, see `story:drive-entry-skill`).

.engineering/planning/story/docs-manifest-links-resolve.md

@@ -0,0 +1,32 @@
+---
+format: aep.planning-md/3
+id: story:docs-manifest-links-resolve
+kind: story
+status: active
+title: agentplugins-check refuses a b10x.docs.yaml URL that names no page
+summary: Every https://beyond10x.github.io/docs/agentplugins/<path>/ in b10x.docs.yaml maps to website/docs/<path>.md.
+scope:
+- confidence: cited
+  path: crates/agentplugins-check/src/main.rs
+revision: 4
+transitions:
+- {from: "draft", to: "proposed", at: "2026-09-28T13:12:54Z", actor: "human:timo", revision: 2}
+- {from: "proposed", to: "active", at: "2026-09-28T13:12:54Z", actor: "human:timo", revision: 3}
+---
+# Story: the docs manifest links resolve
+
+## Outcome
+A `b10x.docs.yaml` section URL under this repository's route base that names no page fails
+`task check`, before it reaches the public website build.
+
+## Context
+From 2026-09-24 to 2026-09-28 every Atlas "Publish unified documentation" run failed: the only
+broken link was `/ecosystem/agentplugins/` → `/docs/agentplugins/plugins/beyond10x/`, the reference
+URL `b10x.docs.yaml` kept after 0.14.0 renamed that page (atlas run 36390633830). The public site
+stayed on the 2026-09-24 08:20 publication for four days. 0.17.0 fixed the URL.
+
+## Acceptance
+`agentplugins-check` maps every `url` in `b10x.docs.yaml` that starts with the surface's
+`canonicalUrl` to `website/docs/<path>.md` (or `<path>/index.md`, or the intro at the root) and
+refuses one with no page, naming the line; a unit test shows the old `plugins/beyond10x/` URL
+refused.

.engineering/planning/story/shared-docs-toolchain.md

@@ -2,12 +2,16 @@
 format: aep.planning-md/3
 id: story:shared-docs-toolchain
 kind: story
-status: draft
+status: implemented
 title: Align the passive producer with the shared contract viewer runtime
 scope:
 - confidence: cited
   path: .github/workflows/b10x-docs-bundle.yml
-revision: 2
+revision: 6
+transitions:
+- {from: "draft", to: "proposed", at: "2026-09-28T13:12:32Z", actor: "human:timo", revision: 4, decided_on: {"recorded":{"test_result":1}}}
+- {from: "proposed", to: "active", at: "2026-09-28T13:12:32Z", actor: "human:timo", revision: 5, decided_on: {"recorded":{"test_result":1}}}
+- {from: "active", to: "implemented", at: "2026-09-28T13:12:33Z", actor: "human:timo", revision: 6, decided_on: {"recorded":{"test_result":1}}}
 ---
 ## Outcome
 
@@ -20,3 +24,11 @@ The Atlas-generated producer caller pins Docs System commit 1d4c0262911761118ffd
 ## Scope
 
 .github/workflows/b10x-docs-bundle.yml and this planning record. The coordinating authority is the shared documentation rollout; this repository's product/runtime contracts do not change.
+
+## Resolution
+
+Delivered by a later pin. `.github/workflows/b10x-docs-bundle.yml` runs
+`beyond10x/docs-system/.github/actions/bundle@339b4b8462f19b4c9d3716e6a44ed2a3691eb9d8`
+(2026-09-23, "a v5 registry surface is a documentation surface"), and 1d4c026 is an ancestor of
+339b4b8 (`git merge-base --is-ancestor`), so the reviewed runtime this story named is in force.
+The producer ran credential-free on 44bb0ee and succeeded (run 36406238132, 2026-09-28).

.engineering/project.yaml

@@ -1,7 +1,7 @@
 planning_scope: agentplugins
 profile: development.standard
 protocol: adp/1
-protocols: git+https://github.com/beyond10x/aep#b857bbebcb44f77275bc745659226f4826897e78
+protocols: git+https://github.com/beyond10x/aep#58433bd85a1ccf939566c53d5543df86c3852b19
 store:
   git: {}
 summary: Curated Codex and Claude Code plugins for AEP planning, ADP development and ESS validation, planned in their own store.

.github/workflows/eval.yml

@@ -55,8 +55,8 @@ jobs:
       # and this workflow runs the version pinned below, which has neither. A grouped spelling here
       # would not teach a reader anything; it would fail to parse on the runner. Move both when the
       # pin moves.
-      AEP_VERSION: '0.44.0'
-      METAHARNESS_VERSION: '0.4.2'
+      AEP_VERSION: '0.64.0'
+      METAHARNESS_VERSION: '0.8.0'
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
         with:
@@ -195,7 +195,7 @@ jobs:
           # stop at `unrecognized subcommand 'doctor'`; aep 0.45.0's `eval run` refuses a mismatch.
           install -d "$HOME/.local/bin"
           install -m 0755 "aep-${AEP_VERSION}-${target}/aep" "$HOME/.local/bin/aep"
-          cargo install --locked --git https://github.com/beyond10x/metaharness --tag "$METAHARNESS_VERSION" metaharness
+          cargo install --locked --git https://github.com/beyond10x/metaharness --tag "$METAHARNESS_VERSION" metaharness-cli
           aep --version
           metaharness --version
 
@@ -217,7 +217,7 @@ jobs:
             [[ -n "$case" ]] || continue
             echo "::group::$case"
             case_out="$RUNNER_TEMP/eval-out/${case#evals/}"
-            aep eval run \
+            metaharness aep drive eval run \
               --case "$case" \
               --arm plugin \
               --harness claude \

AGENTS.md

@@ -17,6 +17,7 @@ CLIs. Serves O2 (decisions as data) and O3 (any harness).
 | `website/` | public docs; must pass `task site-build` |
 | `SETUP.md` | agent bootstrap, published as a release asset |
 | `.agents/skills/improving-by-trial/` | how plugins are improved: isolated headless trials (`task trial:sandbox`, `task trial:run`), triage, fix, re-run |
+| `.agents/skills/following-upstream/` | how this repository follows the releases, workflow pins and issues it depends on: `agentplugins-check upstream` reports what moved, then update, verify, release, follow downstream |
 | `trials/` | the round's trial definitions (`<name>/trial.yaml`, fixtures) and `baseline.json`; `task trial:run TRIAL=<name>` runs one, `agentplugins-check trial-report` measures it against the baseline |
 
 ## Rules
@@ -41,6 +42,7 @@ CLIs. Serves O2 (decisions as data) and O3 (any harness).
 task check          # fmt, clippy, tests, agentplugins-check (includes the trial definitions)
 task site-build     # when website/ changes
 cargo run --locked --bin agentplugins-check -- tools    # network: every spelled command exists in the newest aep, ess, worktree
+cargo run --locked --bin agentplugins-check -- upstream # network: what moved upstream (releases and changelogs, workflow pins, cited issues)
 ```
 
 ## Planning

CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## [0.18.0] — 2026-09-28
+
+A second tutorial continues the first: the ESS tutorial's library gets an AEP plan, four critics
+review it, and the first story is built in a reviewed wave. The skills are verified against aep
+0.64.0 and ess 0.39.0, and a new report and skill keep this repository in step with the releases
+it depends on.
+
+- New page: [Your first governed plan](website/docs/tutorials/first-governed-plan.md), recorded with
+  aep 0.64.0 and ess 0.39.0: adopt an `aep.project/5` store, model a new state in ESS before any
+  story is written (17 → 55 scenarios), six stories, four critic verdicts, a wave proposal, and one
+  story implemented, attacked by the adversary and merged. The `aep-tutorial` trial has a fresh
+  agent follow it.
+- `agentplugins-check upstream` reports what moved in every repository this one depends on: the
+  releases its plugins drive with their changelog sections, the `beyond10x/*` workflow pins, and
+  the issues its text cites. `.agents/skills/following-upstream` is the loop that acts on it.
+- `agentplugins-check` refuses a `b10x.docs.yaml` link that names no page. One such link
+  (`plugins/beyond10x/`, renamed in 0.14.0) failed every organization website publication from
+  2026-09-24 to 2026-09-28.
+- `verified.json` pins aep 0.64.0 and ess 0.39.0. `ess:retrofitting` and `syntax.md`: a read by
+  identity is the unfiltered view; `filter: id == param.id` leaves every outcome it observes
+  unsynthesized (beyond10x/ess#193). `ess:hardening` covers the concurrent explorer and
+  `ess verify conform check-history`.
+- `aep:planning` checks each critic's verdict line before recording it; the decomposer relates each
+  story to the epic's objective, which `development.standard` requires before a story is accepted.
+- Eval recording moved to `metaharness aep drive eval run` with aep 0.64.0; it is blocked until
+  metaharness links a current aep (beyond10x/metaharness#10). The four plan-critic cases have a
+  working tree, `fixtures/library-reservations-drafted`.
+- `task trial:sandbox` can recreate a sandbox that ran `aep`.
+
 ## [0.17.0] — 2026-09-28
 
 A tutorial takes a developer from an empty directory to a validated ESS specification and a Go

Cargo.toml

@@ -3,7 +3,7 @@ resolver = "2"
 members = ["crates/agentplugins-check", "crates/b10x"]
 
 [workspace.package]
-version = "0.17.0"
+version = "0.18.0"
 edition = "2021"
 rust-version = "1.85"
 license = "Apache-2.0"

Taskfile.yml

@@ -42,7 +42,8 @@ tasks:
             fi
           done
         done
-      - rm -rf '{{.T}}'
+      # aep makes its protocol snapshots read-only; a sandbox that ran aep cannot be removed without this.
+      - if [ -d '{{.T}}' ]; then chmod -R u+w '{{.T}}'; fi; rm -rf '{{.T}}'
       - mkdir -p -m 700 '{{.TRIALS}}'
       - mkdir -p '{{.T}}/home/.local/bin' '{{.T}}/work' '{{.T}}/tools'
       - for t in claude codex go gofmt; do p="$(command -v $t)" && ln -sf "$(readlink -f "$p")" '{{.T}}/tools/'$t; done; true

b10x.docs.yaml

@@ -60,6 +60,9 @@ surfaces:
   - kind: guide
     label: 'Tutorial: your first ESS specification'
     url: https://beyond10x.github.io/docs/agentplugins/tutorials/first-ess-specification/
+  - kind: guide
+    label: 'Tutorial: your first governed plan'
+    url: https://beyond10x.github.io/docs/agentplugins/tutorials/first-governed-plan/
   - kind: reference
     label: Plugin reference
     url: https://beyond10x.github.io/docs/agentplugins/plugins/b10x/