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

.cursor/rules/learnings-index.mdc

@@ -44,6 +44,12 @@ propose a retirement, a consolidation, or a glob-scoped sub-index split.
   as the idempotent hygiene hooks (skill links, learnings sync): never
   raise, network only as a bounded pull before distribution.
   → .cursor/skills/architecture/hook-points/
+- [architecture/command-runner-exec] When adding a dev command or any
+  step that must run after one (installed stamp, hygiene hooks): project
+  `run:` commands exec-replace the dev process, so nothing after
+  `cmd.execute` in Runner#run runs for them — post-command work needs a
+  builtin or spawn-and-wait (dev#85).
+  → .cursor/skills/learnings/command-runner-exec/
 
 ## toolchain
 

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

@@ -19,10 +19,12 @@ description: >-
   `.cursor/rules/separation-of-concerns.mdc`: Repository resolves,
   Integration installs, Lockfile serializes, the orchestrator
   coordinates — one class, one layer.
-- **`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/learnings/`** — the learnings read path plus its scaffold:
+  Cache (bounded clone/pull of the knowledge repo), Synchronizer
+  (orchestration), InvariantsRenderer (machine-side render + per-project
+  symlink + the `dev learnings invariants` prompt seam), Layout (canonical
+  owner of both tiers' paths and index templates; ai-flow mirrors them),
+  Scaffolder (`dev learnings init`'s write-once materialization).
 - **`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`.

.cursor/skills/learnings/command-runner-exec/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: command-runner-exec
+description: >-
+  MUST be used when adding a dev command, sequencing work after
+  cmd.execute in Dev::Runner#run, or diagnosing a post-command step (like
+  the installed stamp) that silently never happens.
+---
+
+# CommandRunner exec ends the dev process
+
+`Dev::CommandRunner` runs project `run:` commands with `Kernel.exec` — the
+dev process is replaced, so nothing after `cmd.execute` in
+`Dev::Runner#run` executes for a yaml-declared command, nor for an
+`OverriddenCommand` whose body is one. Post-execute steps only ever run
+for fully in-process builtins — which makes this an input to command
+placement: a builtin can carry post-steps, a `run:` command cannot.
+
+Wrong — a follow-up step after execute, expecting it for every command:
+
+    cmd.execute(args:, context:)
+    stamp_installed(cmd_name, context.project_root) # skipped on exec
+
+Also wrong: hoisting the step before execute, when it records an outcome
+(the stamp means "provisioning *succeeded*" — stamping first marks a
+failed `dev up` as installed). Success-contingent work needs the command
+to run in-process: spawn-and-wait with the exit status propagated, not
+exec-replace — that fix is dev#85. Only outcome-independent work may
+move before the exec point.
+
+Observed symptom: in a repo whose dev.yml defines `up:`, `dev up` exec's
+into the project's up command and never reaches `stamp_installed`, so the
+staleness gate keeps reporting "never installed" — fatal in a CI=true
+shell. `dev install-deps` stays in-process and stamps. Check this before
+suspecting the staleness digests themselves.
+
+learned-from: dev#73 build pass (dev up never stamped; install-deps did);
+the sequencing bug itself is dev#85
+date: 2026-08-02