Repository navigation
Release train: docs parity — AGENTS.md, GLOSSARY.md, skills #577
Description
What to build: Rewrite every agent-facing passage the release train invalidates, per the cleanup inventory: AGENTS.md's pin-lifecycle paragraph ("stale pin resolves only while the 24h cache stands in") replaced with slot-first permanent resolution; the npm-publish, image-tag cadence, and "stamps the previous frameworkVersion" passages updated for the train; the changesets release-capture rule spelled out; the Dockerfile Railway claim removed. GLOSSARY.md: the platform-release-manifest and derived-pin entries gain the versioned slots + release-scoped pointer semantics. The skills (publish-sync, registry, extends-config, cli-reference, init-upgrade) get the same treatment: skip-on-registry-failure passages → hard-fail release legs; "full trains only" → "release legs"; stale-pin repair passages → old pins always resolvable; registry key layout gains platform-versions/<version>.json.
Blocked by: #573, #574, #575 …
Status: ready-for-agent
- AGENTS.md passages rewritten (pin lifecycle, deploy/publish descriptions, changesets rules, Dockerfile removal)
- GLOSSARY.md platform-release-manifest + derived-pin entries match the new model
- All five skills' inventoried passages rewritten; grep for stale phrases ("skips the manifest for that deploy", "24h", "stale pin") across AGENTS/GLOSSARY/skills returns only intentional historical mentions
- Agent-facing vocabulary includes: owed work, release leg, versioned slot, drift alarm (in-train + manual
bos upgrade --check)
Activity
elliotBraem commentedon Oct 24, 2026
Concrete parity gaps found while aligning a child (
citynode.app, PR NEARBuilders/citynode.app#428), which this release train's docs work should fold in:buildChildAgentsMd(services/scaffold) rebuilds the entire authored half frombuildChildAgentsInstructions(opts), and sync rewrites it when the local hash drifts. Two consequences: template corrections to the authored half (e.g. the_layout/_authenticatedauth-check sample that no composed child uses — the real shape is mounts_public/_authenticated/_adminwithrequireSession/requireAdmin) need a child-owned block mechanism likeplugin.dev.ts's// child-owned-start, or child corrections must land in the template. Our corrections (local-vs-remote plugins, mount-based sample, runtime-map section) are in the child PR as the reference diff.skills-lock.json, and the descriptions teach retired shapes (bos.config.json— the authored descriptor isbos.app.ts;better-near-authpinned at 1.8.2 while the platform train is on 2.0.0-rc.x). Trim + refresh the lock.docs/agents/**in the template so every child inherits it.CODING_STANDARDS.mdscaffold for children would give the write-once / type-safety goals a stable review-time home (currently child-local, and children each re-author it).Child-reference for all of the above: citynode PR #428 +
docs/agents/change-placement.md.elliotBraem commentedon Oct 24, 2026
Now dedicated tickets for the two concrete mechanisms described here:
types:geninventory emission (child stops hand-wiring): everything-dev#594