ai-flow /learn: learnings from d3mlabs/dev#74

.cursor/rules/learnings-index.mdc

@@ -34,15 +34,15 @@ propose a retirement, a consolidation, or a glob-scoped sub-index split.
 ## architecture
 
 - [architecture/command-dispatch] Global builtins (cd, plan, cred,
-  knowledge) dispatch before the dev.yml gate; project commands are
+  learnings) dispatch before the dev.yml gate; project commands are
   yaml-declared and run through Runner.
   → .cursor/skills/architecture/command-dispatch/
 - [architecture/module-map] What owns what: src/dev is the typed CLI core;
   each `lib/dev/<module>` is one feature whose Accessor is its only CLI
   surface. → .cursor/skills/architecture/module-map/
 - [architecture/hook-points] `dev up` / `install-deps` / `dev plan` double
-  as the idempotent hygiene hooks (skill links, knowledge sync): never
-  raise, never block on the network.
+  as the idempotent hygiene hooks (skill links, learnings sync): never
+  raise, network only as a bounded pull before distribution.
   → .cursor/skills/architecture/hook-points/
 
 ## toolchain
@@ -56,7 +56,7 @@ propose a retirement, a consolidation, or a glob-scoped sub-index split.
 ## org tier
 
 Org-wide invariants and knowledge live in the configured org knowledge
-repo (`knowledge_repo:`), not here: dev renders the always-on slice into
-the generated `.cursor/rules/org-invariants.mdc` and links the on-demand
-corpus into `~/.cursor/skills/`. A lesson about how we build software —
-not about this repo — belongs there.
+repo (`knowledge_repo:`), not here: dev renders the always-on slice once
+machine-side and links it in as `.cursor/rules/org-invariants.mdc`, and
+links the on-demand corpus into `~/.cursor/skills/`. A lesson about how
+we build software — not about this repo — belongs there.

.cursor/skills/architecture/command-dispatch/SKILL.md

@@ -12,7 +12,7 @@ routes argv through two layers:
 
 1. **Global builtins** — `Dev::GlobalDispatch`
    (`src/dev/global_dispatch.rb`) runs first, before any dev.yml lookup,
-   so `cd`, `plan`, `cred`, and `knowledge` work from any directory. Each
+   so `cd`, `plan`, `cred`, and `learnings` work from any directory. Each
    owns host- or workspace-global state, never project config.
 2. **Project commands** — everything else builds `Dev::Runner`
    (`src/dev/runner.rb`), which requires a dev.yml in the cwd's ancestry
@@ -25,7 +25,7 @@ The seams:
 - A new global command joins `GlobalDispatch::GLOBAL_COMMANDS` and gets a
   feature module under `lib/dev/<name>/` whose `Accessor` is its only CLI
   surface (usage, arg parsing, clean failures) — see `Cd::Accessor`,
-  `Plan::Accessor`, `Knowledge::Accessor`.
+  `Plan::Accessor`, `Learnings::Accessor`.
 - Project commands are declared in each repo's dev.yml, never hardcoded
   in dev's core.
 - Workspace-global commands resolve their root as nearest dev.yml, else

.cursor/skills/architecture/hook-points/SKILL.md

@@ -9,22 +9,25 @@ description: >-
 
 `dev up` / `dev install-deps` (`Runner#install_locked_deps`) and every
 `dev plan` invocation (`Plan::Accessor#run`) double as the refresh points
-for agent-facing hygiene: shipped-skill links, gem-skill links, the org
-knowledge TTL fetch, and the org-invariants render. There is no separate
-setup step by design — riding existing commands is what keeps the
-artifacts fresh without asking anything of the user.
+for agent-facing hygiene: shipped-skill links, gem-skill links, the
+knowledge repo cache pull, and the org-invariants render + project link.
+There is no separate setup step by design — riding existing commands is
+what keeps the artifacts fresh without asking anything of the user.
 
 Anything added to a hook point must obey both rules:
 
 - **Hygiene must not block correctness.** The hook paths never raise —
   failures warn on stderr and the carrying command proceeds (see
-  `GemSkillLinker#link_all`, `Knowledge::Synchronizer#sync`,
+  `GemSkillLinker#link_all`, `Learnings::Synchronizer#sync`,
   `SkillInstaller#install`).
-- **No network on the hot path.** Remote refreshes are TTL-gated and
-  async (`Knowledge::Cache#refresh_async`); the synchronous work is
-  idempotent, content-compared, millisecond-scale symlink and render
-  checks. Blocking network belongs only behind an explicit command
-  (`dev knowledge sync`).
+- **Network on the hot path is bounded and ordered.** The cache pull runs
+  inline *before* distribution (a hook never renders content it just
+  found stale), capped by a ~2s timeout with a ~30s courtesy floor
+  (`Learnings::Cache#refresh_bounded`, constants, not settings); on
+  timeout or offline the current cache is served. The rest is idempotent,
+  content-compared, millisecond-scale symlink and render checks.
+  Unbounded blocking network belongs only behind an explicit command
+  (`dev learnings sync` — the runner bootstrap contract's step).
 
 origin: seeded by the dev#58 architecture pass
 date: 2026-07-25

.cursor/skills/architecture/module-map/SKILL.md

@@ -19,9 +19,10 @@ description: >-
   `.cursor/rules/separation-of-concerns.mdc`: Repository resolves,
   Integration installs, Lockfile serializes, the orchestrator
   coordinates — one class, one layer.
-- **`lib/dev/knowledge/`** — org knowledge distribution: Cache (TTL git
-  clone), Synchronizer (orchestration), InvariantsRenderer (the generated
-  org-invariants.mdc).
+- **`lib/dev/learnings/`** — the learnings read path: Cache (bounded git
+  clone/pull of the knowledge repo), Synchronizer (orchestration),
+  InvariantsRenderer (one machine-side org-invariants.mdc render plus the
+  per-project symlink and the `dev learnings invariants` prompt seam).
 - **`lib/dev/skill_installer.rb`** — the one symlink mechanism behind all
   three skill channels (shipped, org, gem); the gem channel's lockfile
   scan is `lib/dev/deps/gem_skill_linker.rb`.