Two changes in the same territory, one issue: the command-surface consolidation settled in the four-role design session (org-architecture skill has the doctrine), and the distribution-freshness fixes the cellbound-3d#151 / runner work surfaced.
Consolidate under dev learnings
The vocabulary: a learning is the artifact at either tier; the knowledge repo is a proper noun. Commands are named by the artifact they operate on, so the dev knowledge family retires:
- Rename end to end: global dispatch (
bin/dev, global_dispatch.rb), Knowledge::Accessor usage text, the runner.rb help registration, module names (Dev::Knowledge → Dev::Learnings). No alias/deprecation ceremony — pre-1.0, one operator.
dev learnings sync (bare, blocking): refreshes the whole read path — org cache pull, invariants render into the project at hand, gem-skill relinks; outside a project it does the machine-global parts and skips the render. No tier flag: tier is an implementation detail of "current", and syncing everything is what you want 100% of the time. Errors bubble (the user asked).dev learnings status: configured knowledge repo, cache location/age, what's rendered/linked (per tier).dev learnings invariants: prints the Tier-0 prompt block (the invariants section extracted from the org index). This is the seam ai-flow's OrgInvariants shells out to instead of mirroring the cache path + section parsing (companion ai-flow issue) — and the abstraction point a future derived cache hides behind (dev learnings query; derived index keyed by corpus SHA + embedder version, select-only, disposable).
Tighten distribution
Today admission-to-awareness on the org tier crosses four async boundaries, and the hook that notices staleness still distributes the old cache:
- Drop the
knowledge_ttl knob. The refresh is a detached quiet git pull on a tiny repo — the cost the TTL protects against doesn't exist. Hooks refresh async on every call (a hardcoded ~30s courtesy floor at most, not a config setting); stale?/synced_at FETCH_HEAD-mtime machinery goes with it.
- Fix the distribute-before-refresh ordering in
Knowledge::Synchronizer#sync: hooks should pull inline with a short timeout (1-2s), falling back to the cache on timeout/offline, so a hook never renders content it just found stale.
- Render invariants once cache-side, symlink per project (same shape as the user-global skill links): one refresh updates every project on the machine simultaneously, and a fresh clone's window shrinks to creating one symlink.
- Runner bootstrap contract: an explicit blocking
dev learnings sync step, so agent sessions never start on stale invariants and the dependency is stated in the workflow instead of hiding as a side effect of install_locked_deps (runner.rb:438).
Downstream doc references (follow-up PRs on their own repos)
- ai-flow README adoption checklist + paper Section 3 clause ("A machine-local sync (
dev knowledge)…")
- org-architecture skill already describes the target state (d3mlabs/knowledge#36)
Related: #73 (dev learnings init) joins the same family.
Two changes in the same territory, one issue: the command-surface consolidation settled in the four-role design session (org-architecture skill has the doctrine), and the distribution-freshness fixes the cellbound-3d#151 / runner work surfaced.
Consolidate under
dev learningsThe vocabulary: a learning is the artifact at either tier; the knowledge repo is a proper noun. Commands are named by the artifact they operate on, so the
dev knowledgefamily retires:bin/dev,global_dispatch.rb),Knowledge::Accessorusage text, therunner.rbhelp registration, module names (Dev::Knowledge→Dev::Learnings). No alias/deprecation ceremony — pre-1.0, one operator.dev learnings sync(bare, blocking): refreshes the whole read path — org cache pull, invariants render into the project at hand, gem-skill relinks; outside a project it does the machine-global parts and skips the render. No tier flag: tier is an implementation detail of "current", and syncing everything is what you want 100% of the time. Errors bubble (the user asked).dev learnings status: configured knowledge repo, cache location/age, what's rendered/linked (per tier).dev learnings invariants: prints the Tier-0 prompt block (the invariants section extracted from the org index). This is the seam ai-flow'sOrgInvariantsshells out to instead of mirroring the cache path + section parsing (companion ai-flow issue) — and the abstraction point a future derived cache hides behind (dev learnings query; derived index keyed by corpus SHA + embedder version, select-only, disposable).Tighten distribution
Today admission-to-awareness on the org tier crosses four async boundaries, and the hook that notices staleness still distributes the old cache:
knowledge_ttlknob. The refresh is a detached quietgit pullon a tiny repo — the cost the TTL protects against doesn't exist. Hooks refresh async on every call (a hardcoded ~30s courtesy floor at most, not a config setting);stale?/synced_atFETCH_HEAD-mtime machinery goes with it.Knowledge::Synchronizer#sync: hooks should pull inline with a short timeout (1-2s), falling back to the cache on timeout/offline, so a hook never renders content it just found stale.dev learnings syncstep, so agent sessions never start on stale invariants and the dependency is stated in the workflow instead of hiding as a side effect ofinstall_locked_deps(runner.rb:438).Downstream doc references (follow-up PRs on their own repos)
dev knowledge)…")Related: #73 (
dev learnings init) joins the same family.